@victorylabs/params 0.1.0

package/dist/storage/cookie.cjs

@@ -0,0 +1,136 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/storage/cookie/index.ts
+var cookie_exports = {};
+__export(cookie_exports, {
+  cookieStorage: () => cookieStorage
+});
+module.exports = __toCommonJS(cookie_exports);
+var isClient = typeof window !== "undefined" && typeof document !== "undefined";
+var DEFAULT_KEY = "params";
+function cookieStorage(options = {}) {
+  const key = options.key ?? DEFAULT_KEY;
+  const serialize = options.serialize ?? JSON.stringify;
+  const deserialize = options.deserialize ?? JSON.parse;
+  const attrs = options.attributes ?? { path: "/", sameSite: "Lax" };
+  const readImpl = () => {
+    const raw = readRawCookie(key, options.readCookie);
+    if (raw === void 0) return void 0;
+    try {
+      const parsed = deserialize(raw);
+      if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return void 0;
+      }
+      return parsed;
+    } catch {
+      return void 0;
+    }
+  };
+  return {
+    name: "cookie",
+    // Cookies WORK on the server — that's the whole point of this backend.
+    // The store reads on construction, which on the server uses the
+    // closure-bound readCookie. clientOnly stays false.
+    clientOnly: false,
+    read: readImpl,
+    write: (values) => {
+      try {
+        const existing = readImpl() ?? {};
+        const merged = { ...existing };
+        for (const [path, value] of Object.entries(values)) {
+          if (value === void 0) {
+            delete merged[path];
+          } else {
+            merged[path] = value;
+          }
+        }
+        if (Object.keys(merged).length === 0) {
+          writeRawCookie(key, "", { ...attrs, maxAge: 0 }, options.writeCookie);
+          return;
+        }
+        writeRawCookie(key, serialize(merged), attrs, options.writeCookie);
+      } catch {
+      }
+    },
+    clear: (paths) => {
+      try {
+        if (paths.length === 0) {
+          writeRawCookie(key, "", { ...attrs, maxAge: 0 }, options.writeCookie);
+          return;
+        }
+        const existing = readImpl();
+        if (!existing) return;
+        const next = { ...existing };
+        for (const path of paths) delete next[path];
+        if (Object.keys(next).length === 0) {
+          writeRawCookie(key, "", { ...attrs, maxAge: 0 }, options.writeCookie);
+          return;
+        }
+        writeRawCookie(key, serialize(next), attrs, options.writeCookie);
+      } catch {
+      }
+    }
+    // No subscribe — cookies don't have change events. Cross-tab sync would
+    // require BroadcastChannel; out of scope for v0.2.
+  };
+}
+function readRawCookie(key, readCookie) {
+  if (readCookie) {
+    const v = readCookie();
+    return v === void 0 || v === null ? void 0 : decodeURIComponent(v);
+  }
+  if (!isClient) return void 0;
+  return parseCookieJar(document.cookie, key);
+}
+function writeRawCookie(key, value, attrs, writeCookie) {
+  const setCookieValue = formatSetCookie(key, value, attrs);
+  if (writeCookie) {
+    writeCookie(setCookieValue);
+    return;
+  }
+  if (!isClient) return;
+  document.cookie = setCookieValue;
+}
+function parseCookieJar(jar, key) {
+  if (!jar) return void 0;
+  for (const part of jar.split(";")) {
+    const eq = part.indexOf("=");
+    if (eq === -1) continue;
+    const k = part.slice(0, eq).trim();
+    if (k !== key) continue;
+    return decodeURIComponent(part.slice(eq + 1).trim());
+  }
+  return void 0;
+}
+function formatSetCookie(key, value, attrs) {
+  const segments = [`${key}=${encodeURIComponent(value)}`];
+  if (attrs.path !== void 0) segments.push(`Path=${attrs.path}`);
+  if (attrs.maxAge !== void 0) segments.push(`Max-Age=${attrs.maxAge}`);
+  if (attrs.expires !== void 0) segments.push(`Expires=${attrs.expires.toUTCString()}`);
+  if (attrs.domain !== void 0) segments.push(`Domain=${attrs.domain}`);
+  if (attrs.sameSite !== void 0) segments.push(`SameSite=${attrs.sameSite}`);
+  if (attrs.secure) segments.push("Secure");
+  return segments.join("; ");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  cookieStorage
+});
+//# sourceMappingURL=cookie.cjs.map

package/dist/storage/cookie.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/storage/cookie/index.ts"],"sourcesContent":["import type { ParamsStorage } from '../../storage'\n\nexport interface CookieStorageAttributes {\n  path?: string\n  maxAge?: number\n  expires?: Date\n  domain?: string\n  sameSite?: 'Lax' | 'Strict' | 'None'\n  secure?: boolean\n}\n\nexport interface CookieStorageOptions<T> {\n  /** Cookie name. Default: `'params'`. */\n  readonly key?: string\n\n  /**\n   * Server-side: read from the incoming request's cookies. Closure-bound at\n   * factory time. Receives nothing; returns the raw cookie value (already\n   * URL-decoded) or `undefined`.\n   *\n   * If omitted, the backend assumes a client environment and reads from\n   * `document.cookie`.\n   */\n  readonly readCookie?: () => string | undefined\n\n  /**\n   * Server-side: append to the outgoing response. Closure-bound at factory\n   * time. Receives the full `Set-Cookie` header value (e.g. `\"params=foo;\n   * Path=/; SameSite=Lax\"`); the consumer is responsible for actually\n   * sending it to the browser via their framework's response API.\n   *\n   * If omitted, the backend assumes a client environment and writes to\n   * `document.cookie`.\n   */\n  readonly writeCookie?: (setCookieValue: string) => void\n\n  /** Whole-blob serializer. Default: `JSON.stringify`. */\n  readonly serialize?: (values: Partial<T>) => string\n\n  /** Whole-blob deserializer. Default: `JSON.parse`. */\n  readonly deserialize?: (raw: string) => Partial<T> | undefined\n\n  /** Cookie attributes appended to writes. */\n  readonly attributes?: CookieStorageAttributes\n}\n\nconst isClient = typeof window !== 'undefined' && typeof document !== 'undefined'\nconst DEFAULT_KEY = 'params'\n\n/**\n * Cookie-backed storage. Works on both the server (via closure-bound\n * `readCookie` / `writeCookie` adapters) and the client (via\n * `document.cookie`). The whole values blob is JSON-encoded under one\n * cookie key.\n *\n * Use cases:\n *  - User preferences that should survive a hard refresh (theme, locale).\n *  - SSR snapshot transport when paired with `paramsSnapshot()` /\n *    `hydrateParams()`.\n *\n * Cookies have a ~4 KB limit per domain — for filter state, prefer\n * `urlStorage`; for app config not tied to a user account, prefer\n * `localStorage`.\n */\nexport function cookieStorage<T = Record<string, unknown>>(\n  options: CookieStorageOptions<T> = {},\n): ParamsStorage<T> {\n  const key = options.key ?? DEFAULT_KEY\n  const serialize = options.serialize ?? (JSON.stringify as (values: Partial<T>) => string)\n  const deserialize = options.deserialize ?? (JSON.parse as (raw: string) => Partial<T> | undefined)\n  const attrs = options.attributes ?? { path: '/', sameSite: 'Lax' as const }\n\n  const readImpl = (): Partial<T> | undefined => {\n    const raw = readRawCookie(key, options.readCookie)\n    if (raw === undefined) return undefined\n    try {\n      const parsed = deserialize(raw)\n      if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {\n        return undefined\n      }\n      return parsed\n    } catch {\n      return undefined\n    }\n  }\n\n  return {\n    name: 'cookie',\n    // Cookies WORK on the server — that's the whole point of this backend.\n    // The store reads on construction, which on the server uses the\n    // closure-bound readCookie. clientOnly stays false.\n    clientOnly: false,\n    read: readImpl,\n    write: (values) => {\n      try {\n        const existing = readImpl() ?? ({} as Partial<T>)\n        const merged: Record<string, unknown> = { ...existing }\n        for (const [path, value] of Object.entries(values as Record<string, unknown>)) {\n          if (value === undefined) {\n            delete merged[path]\n          } else {\n            merged[path] = value\n          }\n        }\n        if (Object.keys(merged).length === 0) {\n          writeRawCookie(key, '', { ...attrs, maxAge: 0 }, options.writeCookie)\n          return\n        }\n        writeRawCookie(key, serialize(merged as Partial<T>), attrs, options.writeCookie)\n      } catch {\n        // Silent fallback — same contract as other backends.\n      }\n    },\n    clear: (paths) => {\n      try {\n        if (paths.length === 0) {\n          writeRawCookie(key, '', { ...attrs, maxAge: 0 }, options.writeCookie)\n          return\n        }\n        const existing = readImpl()\n        if (!existing) return\n        const next: Record<string, unknown> = { ...(existing as Record<string, unknown>) }\n        for (const path of paths) delete next[path]\n        if (Object.keys(next).length === 0) {\n          writeRawCookie(key, '', { ...attrs, maxAge: 0 }, options.writeCookie)\n          return\n        }\n        writeRawCookie(key, serialize(next as Partial<T>), attrs, options.writeCookie)\n      } catch {\n        // Silent fallback\n      }\n    },\n    // No subscribe — cookies don't have change events. Cross-tab sync would\n    // require BroadcastChannel; out of scope for v0.2.\n  }\n}\n\nfunction readRawCookie(\n  key: string,\n  readCookie: (() => string | undefined) | undefined,\n): string | undefined {\n  if (readCookie) {\n    const v = readCookie()\n    return v === undefined || v === null ? undefined : decodeURIComponent(v)\n  }\n  if (!isClient) return undefined\n  return parseCookieJar(document.cookie, key)\n}\n\nfunction writeRawCookie(\n  key: string,\n  value: string,\n  attrs: CookieStorageAttributes,\n  writeCookie: ((setCookieValue: string) => void) | undefined,\n): void {\n  const setCookieValue = formatSetCookie(key, value, attrs)\n  if (writeCookie) {\n    writeCookie(setCookieValue)\n    return\n  }\n  if (!isClient) return\n  document.cookie = setCookieValue\n}\n\nfunction parseCookieJar(jar: string, key: string): string | undefined {\n  if (!jar) return undefined\n  for (const part of jar.split(';')) {\n    const eq = part.indexOf('=')\n    if (eq === -1) continue\n    const k = part.slice(0, eq).trim()\n    if (k !== key) continue\n    return decodeURIComponent(part.slice(eq + 1).trim())\n  }\n  return undefined\n}\n\nfunction formatSetCookie(key: string, value: string, attrs: CookieStorageAttributes): string {\n  const segments: string[] = [`${key}=${encodeURIComponent(value)}`]\n  if (attrs.path !== undefined) segments.push(`Path=${attrs.path}`)\n  if (attrs.maxAge !== undefined) segments.push(`Max-Age=${attrs.maxAge}`)\n  if (attrs.expires !== undefined) segments.push(`Expires=${attrs.expires.toUTCString()}`)\n  if (attrs.domain !== undefined) segments.push(`Domain=${attrs.domain}`)\n  if (attrs.sameSite !== undefined) segments.push(`SameSite=${attrs.sameSite}`)\n  if (attrs.secure) segments.push('Secure')\n  return segments.join('; ')\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AA8CA,IAAM,WAAW,OAAO,WAAW,eAAe,OAAO,aAAa;AACtE,IAAM,cAAc;AAiBb,SAAS,cACd,UAAmC,CAAC,GAClB;AAClB,QAAM,MAAM,QAAQ,OAAO;AAC3B,QAAM,YAAY,QAAQ,aAAc,KAAK;AAC7C,QAAM,cAAc,QAAQ,eAAgB,KAAK;AACjD,QAAM,QAAQ,QAAQ,cAAc,EAAE,MAAM,KAAK,UAAU,MAAe;AAE1E,QAAM,WAAW,MAA8B;AAC7C,UAAM,MAAM,cAAc,KAAK,QAAQ,UAAU;AACjD,QAAI,QAAQ,OAAW,QAAO;AAC9B,QAAI;AACF,YAAM,SAAS,YAAY,GAAG;AAC9B,UAAI,WAAW,QAAQ,OAAO,WAAW,YAAY,MAAM,QAAQ,MAAM,GAAG;AAC1E,eAAO;AAAA,MACT;AACA,aAAO;AAAA,IACT,QAAQ;AACN,aAAO;AAAA,IACT;AAAA,EACF;AAEA,SAAO;AAAA,IACL,MAAM;AAAA;AAAA;AAAA;AAAA,IAIN,YAAY;AAAA,IACZ,MAAM;AAAA,IACN,OAAO,CAAC,WAAW;AACjB,UAAI;AACF,cAAM,WAAW,SAAS,KAAM,CAAC;AACjC,cAAM,SAAkC,EAAE,GAAG,SAAS;AACtD,mBAAW,CAAC,MAAM,KAAK,KAAK,OAAO,QAAQ,MAAiC,GAAG;AAC7E,cAAI,UAAU,QAAW;AACvB,mBAAO,OAAO,IAAI;AAAA,UACpB,OAAO;AACL,mBAAO,IAAI,IAAI;AAAA,UACjB;AAAA,QACF;AACA,YAAI,OAAO,KAAK,MAAM,EAAE,WAAW,GAAG;AACpC,yBAAe,KAAK,IAAI,EAAE,GAAG,OAAO,QAAQ,EAAE,GAAG,QAAQ,WAAW;AACpE;AAAA,QACF;AACA,uBAAe,KAAK,UAAU,MAAoB,GAAG,OAAO,QAAQ,WAAW;AAAA,MACjF,QAAQ;AAAA,MAER;AAAA,IACF;AAAA,IACA,OAAO,CAAC,UAAU;AAChB,UAAI;AACF,YAAI,MAAM,WAAW,GAAG;AACtB,yBAAe,KAAK,IAAI,EAAE,GAAG,OAAO,QAAQ,EAAE,GAAG,QAAQ,WAAW;AACpE;AAAA,QACF;AACA,cAAM,WAAW,SAAS;AAC1B,YAAI,CAAC,SAAU;AACf,cAAM,OAAgC,EAAE,GAAI,SAAqC;AACjF,mBAAW,QAAQ,MAAO,QAAO,KAAK,IAAI;AAC1C,YAAI,OAAO,KAAK,IAAI,EAAE,WAAW,GAAG;AAClC,yBAAe,KAAK,IAAI,EAAE,GAAG,OAAO,QAAQ,EAAE,GAAG,QAAQ,WAAW;AACpE;AAAA,QACF;AACA,uBAAe,KAAK,UAAU,IAAkB,GAAG,OAAO,QAAQ,WAAW;AAAA,MAC/E,QAAQ;AAAA,MAER;AAAA,IACF;AAAA;AAAA;AAAA,EAGF;AACF;AAEA,SAAS,cACP,KACA,YACoB;AACpB,MAAI,YAAY;AACd,UAAM,IAAI,WAAW;AACrB,WAAO,MAAM,UAAa,MAAM,OAAO,SAAY,mBAAmB,CAAC;AAAA,EACzE;AACA,MAAI,CAAC,SAAU,QAAO;AACtB,SAAO,eAAe,SAAS,QAAQ,GAAG;AAC5C;AAEA,SAAS,eACP,KACA,OACA,OACA,aACM;AACN,QAAM,iBAAiB,gBAAgB,KAAK,OAAO,KAAK;AACxD,MAAI,aAAa;AACf,gBAAY,cAAc;AAC1B;AAAA,EACF;AACA,MAAI,CAAC,SAAU;AACf,WAAS,SAAS;AACpB;AAEA,SAAS,eAAe,KAAa,KAAiC;AACpE,MAAI,CAAC,IAAK,QAAO;AACjB,aAAW,QAAQ,IAAI,MAAM,GAAG,GAAG;AACjC,UAAM,KAAK,KAAK,QAAQ,GAAG;AAC3B,QAAI,OAAO,GAAI;AACf,UAAM,IAAI,KAAK,MAAM,GAAG,EAAE,EAAE,KAAK;AACjC,QAAI,MAAM,IAAK;AACf,WAAO,mBAAmB,KAAK,MAAM,KAAK,CAAC,EAAE,KAAK,CAAC;AAAA,EACrD;AACA,SAAO;AACT;AAEA,SAAS,gBAAgB,KAAa,OAAe,OAAwC;AAC3F,QAAM,WAAqB,CAAC,GAAG,GAAG,IAAI,mBAAmB,KAAK,CAAC,EAAE;AACjE,MAAI,MAAM,SAAS,OAAW,UAAS,KAAK,QAAQ,MAAM,IAAI,EAAE;AAChE,MAAI,MAAM,WAAW,OAAW,UAAS,KAAK,WAAW,MAAM,MAAM,EAAE;AACvE,MAAI,MAAM,YAAY,OAAW,UAAS,KAAK,WAAW,MAAM,QAAQ,YAAY,CAAC,EAAE;AACvF,MAAI,MAAM,WAAW,OAAW,UAAS,KAAK,UAAU,MAAM,MAAM,EAAE;AACtE,MAAI,MAAM,aAAa,OAAW,UAAS,KAAK,YAAY,MAAM,QAAQ,EAAE;AAC5E,MAAI,MAAM,OAAQ,UAAS,KAAK,QAAQ;AACxC,SAAO,SAAS,KAAK,IAAI;AAC3B;","names":[]}

package/dist/storage/cookie.d.cts

@@ -0,0 +1,57 @@
+import { P as ParamsStorage } from '../storage-DBLIRR-4.cjs';
+
+interface CookieStorageAttributes {
+    path?: string;
+    maxAge?: number;
+    expires?: Date;
+    domain?: string;
+    sameSite?: 'Lax' | 'Strict' | 'None';
+    secure?: boolean;
+}
+interface CookieStorageOptions<T> {
+    /** Cookie name. Default: `'params'`. */
+    readonly key?: string;
+    /**
+     * Server-side: read from the incoming request's cookies. Closure-bound at
+     * factory time. Receives nothing; returns the raw cookie value (already
+     * URL-decoded) or `undefined`.
+     *
+     * If omitted, the backend assumes a client environment and reads from
+     * `document.cookie`.
+     */
+    readonly readCookie?: () => string | undefined;
+    /**
+     * Server-side: append to the outgoing response. Closure-bound at factory
+     * time. Receives the full `Set-Cookie` header value (e.g. `"params=foo;
+     * Path=/; SameSite=Lax"`); the consumer is responsible for actually
+     * sending it to the browser via their framework's response API.
+     *
+     * If omitted, the backend assumes a client environment and writes to
+     * `document.cookie`.
+     */
+    readonly writeCookie?: (setCookieValue: string) => void;
+    /** Whole-blob serializer. Default: `JSON.stringify`. */
+    readonly serialize?: (values: Partial<T>) => string;
+    /** Whole-blob deserializer. Default: `JSON.parse`. */
+    readonly deserialize?: (raw: string) => Partial<T> | undefined;
+    /** Cookie attributes appended to writes. */
+    readonly attributes?: CookieStorageAttributes;
+}
+/**
+ * Cookie-backed storage. Works on both the server (via closure-bound
+ * `readCookie` / `writeCookie` adapters) and the client (via
+ * `document.cookie`). The whole values blob is JSON-encoded under one
+ * cookie key.
+ *
+ * Use cases:
+ *  - User preferences that should survive a hard refresh (theme, locale).
+ *  - SSR snapshot transport when paired with `paramsSnapshot()` /
+ *    `hydrateParams()`.
+ *
+ * Cookies have a ~4 KB limit per domain — for filter state, prefer
+ * `urlStorage`; for app config not tied to a user account, prefer
+ * `localStorage`.
+ */
+declare function cookieStorage<T = Record<string, unknown>>(options?: CookieStorageOptions<T>): ParamsStorage<T>;
+
+export { type CookieStorageAttributes, type CookieStorageOptions, cookieStorage };

package/dist/storage/cookie.d.ts

@@ -0,0 +1,57 @@
+import { P as ParamsStorage } from '../storage-DBLIRR-4.js';
+
+interface CookieStorageAttributes {
+    path?: string;
+    maxAge?: number;
+    expires?: Date;
+    domain?: string;
+    sameSite?: 'Lax' | 'Strict' | 'None';
+    secure?: boolean;
+}
+interface CookieStorageOptions<T> {
+    /** Cookie name. Default: `'params'`. */
+    readonly key?: string;
+    /**
+     * Server-side: read from the incoming request's cookies. Closure-bound at
+     * factory time. Receives nothing; returns the raw cookie value (already
+     * URL-decoded) or `undefined`.
+     *
+     * If omitted, the backend assumes a client environment and reads from
+     * `document.cookie`.
+     */
+    readonly readCookie?: () => string | undefined;
+    /**
+     * Server-side: append to the outgoing response. Closure-bound at factory
+     * time. Receives the full `Set-Cookie` header value (e.g. `"params=foo;
+     * Path=/; SameSite=Lax"`); the consumer is responsible for actually
+     * sending it to the browser via their framework's response API.
+     *
+     * If omitted, the backend assumes a client environment and writes to
+     * `document.cookie`.
+     */
+    readonly writeCookie?: (setCookieValue: string) => void;
+    /** Whole-blob serializer. Default: `JSON.stringify`. */
+    readonly serialize?: (values: Partial<T>) => string;
+    /** Whole-blob deserializer. Default: `JSON.parse`. */
+    readonly deserialize?: (raw: string) => Partial<T> | undefined;
+    /** Cookie attributes appended to writes. */
+    readonly attributes?: CookieStorageAttributes;
+}
+/**
+ * Cookie-backed storage. Works on both the server (via closure-bound
+ * `readCookie` / `writeCookie` adapters) and the client (via
+ * `document.cookie`). The whole values blob is JSON-encoded under one
+ * cookie key.
+ *
+ * Use cases:
+ *  - User preferences that should survive a hard refresh (theme, locale).
+ *  - SSR snapshot transport when paired with `paramsSnapshot()` /
+ *    `hydrateParams()`.
+ *
+ * Cookies have a ~4 KB limit per domain — for filter state, prefer
+ * `urlStorage`; for app config not tied to a user account, prefer
+ * `localStorage`.
+ */
+declare function cookieStorage<T = Record<string, unknown>>(options?: CookieStorageOptions<T>): ParamsStorage<T>;
+
+export { type CookieStorageAttributes, type CookieStorageOptions, cookieStorage };

package/dist/storage/cookie.js

@@ -0,0 +1,111 @@
+// src/storage/cookie/index.ts
+var isClient = typeof window !== "undefined" && typeof document !== "undefined";
+var DEFAULT_KEY = "params";
+function cookieStorage(options = {}) {
+  const key = options.key ?? DEFAULT_KEY;
+  const serialize = options.serialize ?? JSON.stringify;
+  const deserialize = options.deserialize ?? JSON.parse;
+  const attrs = options.attributes ?? { path: "/", sameSite: "Lax" };
+  const readImpl = () => {
+    const raw = readRawCookie(key, options.readCookie);
+    if (raw === void 0) return void 0;
+    try {
+      const parsed = deserialize(raw);
+      if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return void 0;
+      }
+      return parsed;
+    } catch {
+      return void 0;
+    }
+  };
+  return {
+    name: "cookie",
+    // Cookies WORK on the server — that's the whole point of this backend.
+    // The store reads on construction, which on the server uses the
+    // closure-bound readCookie. clientOnly stays false.
+    clientOnly: false,
+    read: readImpl,
+    write: (values) => {
+      try {
+        const existing = readImpl() ?? {};
+        const merged = { ...existing };
+        for (const [path, value] of Object.entries(values)) {
+          if (value === void 0) {
+            delete merged[path];
+          } else {
+            merged[path] = value;
+          }
+        }
+        if (Object.keys(merged).length === 0) {
+          writeRawCookie(key, "", { ...attrs, maxAge: 0 }, options.writeCookie);
+          return;
+        }
+        writeRawCookie(key, serialize(merged), attrs, options.writeCookie);
+      } catch {
+      }
+    },
+    clear: (paths) => {
+      try {
+        if (paths.length === 0) {
+          writeRawCookie(key, "", { ...attrs, maxAge: 0 }, options.writeCookie);
+          return;
+        }
+        const existing = readImpl();
+        if (!existing) return;
+        const next = { ...existing };
+        for (const path of paths) delete next[path];
+        if (Object.keys(next).length === 0) {
+          writeRawCookie(key, "", { ...attrs, maxAge: 0 }, options.writeCookie);
+          return;
+        }
+        writeRawCookie(key, serialize(next), attrs, options.writeCookie);
+      } catch {
+      }
+    }
+    // No subscribe — cookies don't have change events. Cross-tab sync would
+    // require BroadcastChannel; out of scope for v0.2.
+  };
+}
+function readRawCookie(key, readCookie) {
+  if (readCookie) {
+    const v = readCookie();
+    return v === void 0 || v === null ? void 0 : decodeURIComponent(v);
+  }
+  if (!isClient) return void 0;
+  return parseCookieJar(document.cookie, key);
+}
+function writeRawCookie(key, value, attrs, writeCookie) {
+  const setCookieValue = formatSetCookie(key, value, attrs);
+  if (writeCookie) {
+    writeCookie(setCookieValue);
+    return;
+  }
+  if (!isClient) return;
+  document.cookie = setCookieValue;
+}
+function parseCookieJar(jar, key) {
+  if (!jar) return void 0;
+  for (const part of jar.split(";")) {
+    const eq = part.indexOf("=");
+    if (eq === -1) continue;
+    const k = part.slice(0, eq).trim();
+    if (k !== key) continue;
+    return decodeURIComponent(part.slice(eq + 1).trim());
+  }
+  return void 0;
+}
+function formatSetCookie(key, value, attrs) {
+  const segments = [`${key}=${encodeURIComponent(value)}`];
+  if (attrs.path !== void 0) segments.push(`Path=${attrs.path}`);
+  if (attrs.maxAge !== void 0) segments.push(`Max-Age=${attrs.maxAge}`);
+  if (attrs.expires !== void 0) segments.push(`Expires=${attrs.expires.toUTCString()}`);
+  if (attrs.domain !== void 0) segments.push(`Domain=${attrs.domain}`);
+  if (attrs.sameSite !== void 0) segments.push(`SameSite=${attrs.sameSite}`);
+  if (attrs.secure) segments.push("Secure");
+  return segments.join("; ");
+}
+export {
+  cookieStorage
+};
+//# sourceMappingURL=cookie.js.map

package/dist/storage/cookie.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/storage/cookie/index.ts"],"sourcesContent":["import type { ParamsStorage } from '../../storage'\n\nexport interface CookieStorageAttributes {\n  path?: string\n  maxAge?: number\n  expires?: Date\n  domain?: string\n  sameSite?: 'Lax' | 'Strict' | 'None'\n  secure?: boolean\n}\n\nexport interface CookieStorageOptions<T> {\n  /** Cookie name. Default: `'params'`. */\n  readonly key?: string\n\n  /**\n   * Server-side: read from the incoming request's cookies. Closure-bound at\n   * factory time. Receives nothing; returns the raw cookie value (already\n   * URL-decoded) or `undefined`.\n   *\n   * If omitted, the backend assumes a client environment and reads from\n   * `document.cookie`.\n   */\n  readonly readCookie?: () => string | undefined\n\n  /**\n   * Server-side: append to the outgoing response. Closure-bound at factory\n   * time. Receives the full `Set-Cookie` header value (e.g. `\"params=foo;\n   * Path=/; SameSite=Lax\"`); the consumer is responsible for actually\n   * sending it to the browser via their framework's response API.\n   *\n   * If omitted, the backend assumes a client environment and writes to\n   * `document.cookie`.\n   */\n  readonly writeCookie?: (setCookieValue: string) => void\n\n  /** Whole-blob serializer. Default: `JSON.stringify`. */\n  readonly serialize?: (values: Partial<T>) => string\n\n  /** Whole-blob deserializer. Default: `JSON.parse`. */\n  readonly deserialize?: (raw: string) => Partial<T> | undefined\n\n  /** Cookie attributes appended to writes. */\n  readonly attributes?: CookieStorageAttributes\n}\n\nconst isClient = typeof window !== 'undefined' && typeof document !== 'undefined'\nconst DEFAULT_KEY = 'params'\n\n/**\n * Cookie-backed storage. Works on both the server (via closure-bound\n * `readCookie` / `writeCookie` adapters) and the client (via\n * `document.cookie`). The whole values blob is JSON-encoded under one\n * cookie key.\n *\n * Use cases:\n *  - User preferences that should survive a hard refresh (theme, locale).\n *  - SSR snapshot transport when paired with `paramsSnapshot()` /\n *    `hydrateParams()`.\n *\n * Cookies have a ~4 KB limit per domain — for filter state, prefer\n * `urlStorage`; for app config not tied to a user account, prefer\n * `localStorage`.\n */\nexport function cookieStorage<T = Record<string, unknown>>(\n  options: CookieStorageOptions<T> = {},\n): ParamsStorage<T> {\n  const key = options.key ?? DEFAULT_KEY\n  const serialize = options.serialize ?? (JSON.stringify as (values: Partial<T>) => string)\n  const deserialize = options.deserialize ?? (JSON.parse as (raw: string) => Partial<T> | undefined)\n  const attrs = options.attributes ?? { path: '/', sameSite: 'Lax' as const }\n\n  const readImpl = (): Partial<T> | undefined => {\n    const raw = readRawCookie(key, options.readCookie)\n    if (raw === undefined) return undefined\n    try {\n      const parsed = deserialize(raw)\n      if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {\n        return undefined\n      }\n      return parsed\n    } catch {\n      return undefined\n    }\n  }\n\n  return {\n    name: 'cookie',\n    // Cookies WORK on the server — that's the whole point of this backend.\n    // The store reads on construction, which on the server uses the\n    // closure-bound readCookie. clientOnly stays false.\n    clientOnly: false,\n    read: readImpl,\n    write: (values) => {\n      try {\n        const existing = readImpl() ?? ({} as Partial<T>)\n        const merged: Record<string, unknown> = { ...existing }\n        for (const [path, value] of Object.entries(values as Record<string, unknown>)) {\n          if (value === undefined) {\n            delete merged[path]\n          } else {\n            merged[path] = value\n          }\n        }\n        if (Object.keys(merged).length === 0) {\n          writeRawCookie(key, '', { ...attrs, maxAge: 0 }, options.writeCookie)\n          return\n        }\n        writeRawCookie(key, serialize(merged as Partial<T>), attrs, options.writeCookie)\n      } catch {\n        // Silent fallback — same contract as other backends.\n      }\n    },\n    clear: (paths) => {\n      try {\n        if (paths.length === 0) {\n          writeRawCookie(key, '', { ...attrs, maxAge: 0 }, options.writeCookie)\n          return\n        }\n        const existing = readImpl()\n        if (!existing) return\n        const next: Record<string, unknown> = { ...(existing as Record<string, unknown>) }\n        for (const path of paths) delete next[path]\n        if (Object.keys(next).length === 0) {\n          writeRawCookie(key, '', { ...attrs, maxAge: 0 }, options.writeCookie)\n          return\n        }\n        writeRawCookie(key, serialize(next as Partial<T>), attrs, options.writeCookie)\n      } catch {\n        // Silent fallback\n      }\n    },\n    // No subscribe — cookies don't have change events. Cross-tab sync would\n    // require BroadcastChannel; out of scope for v0.2.\n  }\n}\n\nfunction readRawCookie(\n  key: string,\n  readCookie: (() => string | undefined) | undefined,\n): string | undefined {\n  if (readCookie) {\n    const v = readCookie()\n    return v === undefined || v === null ? undefined : decodeURIComponent(v)\n  }\n  if (!isClient) return undefined\n  return parseCookieJar(document.cookie, key)\n}\n\nfunction writeRawCookie(\n  key: string,\n  value: string,\n  attrs: CookieStorageAttributes,\n  writeCookie: ((setCookieValue: string) => void) | undefined,\n): void {\n  const setCookieValue = formatSetCookie(key, value, attrs)\n  if (writeCookie) {\n    writeCookie(setCookieValue)\n    return\n  }\n  if (!isClient) return\n  document.cookie = setCookieValue\n}\n\nfunction parseCookieJar(jar: string, key: string): string | undefined {\n  if (!jar) return undefined\n  for (const part of jar.split(';')) {\n    const eq = part.indexOf('=')\n    if (eq === -1) continue\n    const k = part.slice(0, eq).trim()\n    if (k !== key) continue\n    return decodeURIComponent(part.slice(eq + 1).trim())\n  }\n  return undefined\n}\n\nfunction formatSetCookie(key: string, value: string, attrs: CookieStorageAttributes): string {\n  const segments: string[] = [`${key}=${encodeURIComponent(value)}`]\n  if (attrs.path !== undefined) segments.push(`Path=${attrs.path}`)\n  if (attrs.maxAge !== undefined) segments.push(`Max-Age=${attrs.maxAge}`)\n  if (attrs.expires !== undefined) segments.push(`Expires=${attrs.expires.toUTCString()}`)\n  if (attrs.domain !== undefined) segments.push(`Domain=${attrs.domain}`)\n  if (attrs.sameSite !== undefined) segments.push(`SameSite=${attrs.sameSite}`)\n  if (attrs.secure) segments.push('Secure')\n  return segments.join('; ')\n}\n"],"mappings":"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","names":[]}

package/dist/storage/idb.cjs

@@ -0,0 +1,144 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/storage/idb/index.ts
+var idb_exports = {};
+__export(idb_exports, {
+  idbStorage: () => idbStorage
+});
+module.exports = __toCommonJS(idb_exports);
+var isClient = typeof window !== "undefined" && typeof window.indexedDB !== "undefined";
+function idbStorage(opts) {
+  const dbName = opts.db;
+  const storeName = opts.store ?? "params";
+  const recordKey = opts.key ?? "default";
+  const version = opts.version ?? 1;
+  let dbHandle;
+  const openDb = async () => {
+    if (!isClient) throw new Error("idbStorage: window.indexedDB unavailable");
+    if (dbHandle && dbHandle.version === version) return dbHandle;
+    return new Promise((resolve, reject) => {
+      const req = window.indexedDB.open(dbName, version);
+      req.onupgradeneeded = () => {
+        const db = req.result;
+        if (!db.objectStoreNames.contains(storeName)) {
+          db.createObjectStore(storeName);
+        }
+      };
+      req.onsuccess = () => {
+        dbHandle = req.result;
+        dbHandle.onclose = () => {
+          dbHandle = void 0;
+        };
+        resolve(req.result);
+      };
+      req.onerror = () => reject(req.error);
+    });
+  };
+  const withVersionRetry = async (op) => {
+    try {
+      return await op(await openDb());
+    } catch (err) {
+      const isVersionError = typeof DOMException !== "undefined" && err instanceof DOMException && err.name === "VersionError";
+      if (!isVersionError) throw err;
+      try {
+        dbHandle?.close();
+      } catch {
+      }
+      dbHandle = void 0;
+      return op(await openDb());
+    }
+  };
+  return {
+    name: "idbStorage",
+    clientOnly: true,
+    // IDB has no synchronous API. Engine consults `readAsync` for hydration;
+    // `read()` always returns undefined.
+    read: () => void 0,
+    readAsync: async () => {
+      if (!isClient) return void 0;
+      try {
+        return await withVersionRetry(
+          (db) => new Promise((resolve, reject) => {
+            const tx = db.transaction(storeName, "readonly");
+            const req = tx.objectStore(storeName).get(recordKey);
+            req.onsuccess = () => resolve(req.result ?? void 0);
+            req.onerror = () => reject(req.error);
+          })
+        );
+      } catch {
+        return void 0;
+      }
+    },
+    write: async (values, _changed, _options) => {
+      if (!isClient) return;
+      try {
+        await withVersionRetry(
+          (db) => new Promise((resolve, reject) => {
+            const tx = db.transaction(storeName, "readwrite");
+            const req = tx.objectStore(storeName).put(values, recordKey);
+            req.onsuccess = () => resolve();
+            req.onerror = () => reject(req.error);
+          })
+        );
+      } catch {
+      }
+    },
+    clear: async (paths, _options) => {
+      if (!isClient) return;
+      try {
+        if (paths.length === 0) {
+          await withVersionRetry(
+            (db) => new Promise((resolve, reject) => {
+              const tx = db.transaction(storeName, "readwrite");
+              const req = tx.objectStore(storeName).delete(recordKey);
+              req.onsuccess = () => resolve();
+              req.onerror = () => reject(req.error);
+            })
+          );
+          return;
+        }
+        const current = await withVersionRetry(
+          (db) => new Promise((resolve, reject) => {
+            const tx = db.transaction(storeName, "readonly");
+            const req = tx.objectStore(storeName).get(recordKey);
+            req.onsuccess = () => resolve(req.result ?? {});
+            req.onerror = () => reject(req.error);
+          })
+        );
+        for (const p of paths) delete current[p];
+        await withVersionRetry(
+          (db) => new Promise((resolve, reject) => {
+            const tx = db.transaction(storeName, "readwrite");
+            const req = tx.objectStore(storeName).put(current, recordKey);
+            req.onsuccess = () => resolve();
+            req.onerror = () => reject(req.error);
+          })
+        );
+      } catch {
+      }
+    }
+    // No `subscribe` — IDB doesn't fire native change events. v0.6+ via BroadcastChannel.
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  idbStorage
+});
+//# sourceMappingURL=idb.cjs.map

package/dist/storage/idb.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/storage/idb/index.ts"],"sourcesContent":["import type { ParamsStorage } from '../../storage'\n\nexport interface IdbStorageOptions {\n  /** Database name. Required. */\n  readonly db: string\n  /** Object store name within the database. Default: `'params'`. */\n  readonly store?: string\n  /** Record key within the store. Default: `'default'`. */\n  readonly key?: string\n  /** Schema version. Bump if you change the value shape across releases. Default: `1`. */\n  readonly version?: number\n}\n\nconst isClient = typeof window !== 'undefined' && typeof window.indexedDB !== 'undefined'\n\n/**\n * IndexedDB storage backend.\n *\n * Async-only — `read()` returns `undefined` synchronously; the engine should\n * consult `readAsync()` for hydration. Single record per definition (the\n * `key` option), stored as a structured-clonable object — no JSON\n * serialization layer.\n *\n * v0.5 limitations (likely v0.6+ candidates if a consumer asks):\n *  - **No cross-tab sync** (no BroadcastChannel). The same database is shared\n *    across tabs, but writes from one tab don't push to another. Subscribe is\n *    intentionally absent.\n *  - **No consumer-supplied `onupgradeneeded` hook.** The `version` option\n *    triggers an upgrade transaction and the lib creates the object store on\n *    first open, but you can't migrate from a previous shape.\n */\nexport function idbStorage<T = Record<string, unknown>>(opts: IdbStorageOptions): ParamsStorage<T> {\n  const dbName = opts.db\n  const storeName = opts.store ?? 'params'\n  const recordKey = opts.key ?? 'default'\n  const version = opts.version ?? 1\n\n  // Cache the database handle. Re-opens on demand if closed.\n  let dbHandle: IDBDatabase | undefined\n  const openDb = async (): Promise<IDBDatabase> => {\n    if (!isClient) throw new Error('idbStorage: window.indexedDB unavailable')\n    if (dbHandle && dbHandle.version === version) return dbHandle\n    return new Promise((resolve, reject) => {\n      const req = window.indexedDB.open(dbName, version)\n      req.onupgradeneeded = () => {\n        const db = req.result\n        if (!db.objectStoreNames.contains(storeName)) {\n          db.createObjectStore(storeName)\n        }\n      }\n      req.onsuccess = () => {\n        dbHandle = req.result\n        dbHandle.onclose = () => {\n          dbHandle = undefined\n        }\n        resolve(req.result)\n      }\n      req.onerror = () => reject(req.error)\n    })\n  }\n\n  /**\n   * v0.5: retry once on `VersionError`. Another tab opening the DB at a\n   * different version invalidates our cached handle. Close it, re-open, and\n   * retry the operation. After one retry, fall back to silent (existing\n   * contract).\n   */\n  const withVersionRetry = async <R>(op: (db: IDBDatabase) => Promise<R>): Promise<R> => {\n    try {\n      return await op(await openDb())\n    } catch (err) {\n      const isVersionError =\n        typeof DOMException !== 'undefined' &&\n        err instanceof DOMException &&\n        err.name === 'VersionError'\n      if (!isVersionError) throw err\n      try {\n        dbHandle?.close()\n      } catch {\n        // ignore — handle may already be invalid\n      }\n      dbHandle = undefined\n      return op(await openDb())\n    }\n  }\n\n  return {\n    name: 'idbStorage',\n    clientOnly: true,\n\n    // IDB has no synchronous API. Engine consults `readAsync` for hydration;\n    // `read()` always returns undefined.\n    read: () => undefined,\n\n    readAsync: async () => {\n      if (!isClient) return undefined\n      try {\n        return await withVersionRetry(\n          (db) =>\n            new Promise<Partial<T> | undefined>((resolve, reject) => {\n              const tx = db.transaction(storeName, 'readonly')\n              const req = tx.objectStore(storeName).get(recordKey)\n              req.onsuccess = () => resolve((req.result as Partial<T> | undefined) ?? undefined)\n              req.onerror = () => reject(req.error)\n            }),\n        )\n      } catch {\n        return undefined\n      }\n    },\n\n    write: async (values, _changed, _options) => {\n      if (!isClient) return\n      try {\n        await withVersionRetry(\n          (db) =>\n            new Promise<void>((resolve, reject) => {\n              const tx = db.transaction(storeName, 'readwrite')\n              const req = tx.objectStore(storeName).put(values, recordKey)\n              req.onsuccess = () => resolve()\n              req.onerror = () => reject(req.error)\n            }),\n        )\n      } catch {\n        // Silent fallback per the storage error contract — values still live in memory.\n      }\n    },\n\n    clear: async (paths, _options) => {\n      if (!isClient) return\n      try {\n        if (paths.length === 0) {\n          // Clear everything — delete the record.\n          await withVersionRetry(\n            (db) =>\n              new Promise<void>((resolve, reject) => {\n                const tx = db.transaction(storeName, 'readwrite')\n                const req = tx.objectStore(storeName).delete(recordKey)\n                req.onsuccess = () => resolve()\n                req.onerror = () => reject(req.error)\n              }),\n          )\n          return\n        }\n        // Per-path clear: read current, omit cleared paths, write back.\n        const current = await withVersionRetry(\n          (db) =>\n            new Promise<Record<string, unknown>>((resolve, reject) => {\n              const tx = db.transaction(storeName, 'readonly')\n              const req = tx.objectStore(storeName).get(recordKey)\n              req.onsuccess = () =>\n                resolve((req.result as Record<string, unknown> | undefined) ?? {})\n              req.onerror = () => reject(req.error)\n            }),\n        )\n        for (const p of paths) delete current[p]\n        await withVersionRetry(\n          (db) =>\n            new Promise<void>((resolve, reject) => {\n              const tx = db.transaction(storeName, 'readwrite')\n              const req = tx.objectStore(storeName).put(current, recordKey)\n              req.onsuccess = () => resolve()\n              req.onerror = () => reject(req.error)\n            }),\n        )\n      } catch {\n        // Silent fallback.\n      }\n    },\n\n    // No `subscribe` — IDB doesn't fire native change events. v0.6+ via BroadcastChannel.\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/storage/idb.d.cts

@@ -0,0 +1,31 @@
+import { P as ParamsStorage } from '../storage-DBLIRR-4.cjs';
+
+interface IdbStorageOptions {
+    /** Database name. Required. */
+    readonly db: string;
+    /** Object store name within the database. Default: `'params'`. */
+    readonly store?: string;
+    /** Record key within the store. Default: `'default'`. */
+    readonly key?: string;
+    /** Schema version. Bump if you change the value shape across releases. Default: `1`. */
+    readonly version?: number;
+}
+/**
+ * IndexedDB storage backend.
+ *
+ * Async-only — `read()` returns `undefined` synchronously; the engine should
+ * consult `readAsync()` for hydration. Single record per definition (the
+ * `key` option), stored as a structured-clonable object — no JSON
+ * serialization layer.
+ *
+ * v0.5 limitations (likely v0.6+ candidates if a consumer asks):
+ *  - **No cross-tab sync** (no BroadcastChannel). The same database is shared
+ *    across tabs, but writes from one tab don't push to another. Subscribe is
+ *    intentionally absent.
+ *  - **No consumer-supplied `onupgradeneeded` hook.** The `version` option
+ *    triggers an upgrade transaction and the lib creates the object store on
+ *    first open, but you can't migrate from a previous shape.
+ */
+declare function idbStorage<T = Record<string, unknown>>(opts: IdbStorageOptions): ParamsStorage<T>;
+
+export { type IdbStorageOptions, idbStorage };

package/dist/storage/idb.d.ts

@@ -0,0 +1,31 @@
+import { P as ParamsStorage } from '../storage-DBLIRR-4.js';
+
+interface IdbStorageOptions {
+    /** Database name. Required. */
+    readonly db: string;
+    /** Object store name within the database. Default: `'params'`. */
+    readonly store?: string;
+    /** Record key within the store. Default: `'default'`. */
+    readonly key?: string;
+    /** Schema version. Bump if you change the value shape across releases. Default: `1`. */
+    readonly version?: number;
+}
+/**
+ * IndexedDB storage backend.
+ *
+ * Async-only — `read()` returns `undefined` synchronously; the engine should
+ * consult `readAsync()` for hydration. Single record per definition (the
+ * `key` option), stored as a structured-clonable object — no JSON
+ * serialization layer.
+ *
+ * v0.5 limitations (likely v0.6+ candidates if a consumer asks):
+ *  - **No cross-tab sync** (no BroadcastChannel). The same database is shared
+ *    across tabs, but writes from one tab don't push to another. Subscribe is
+ *    intentionally absent.
+ *  - **No consumer-supplied `onupgradeneeded` hook.** The `version` option
+ *    triggers an upgrade transaction and the lib creates the object store on
+ *    first open, but you can't migrate from a previous shape.
+ */
+declare function idbStorage<T = Record<string, unknown>>(opts: IdbStorageOptions): ParamsStorage<T>;
+
+export { type IdbStorageOptions, idbStorage };