@victorylabs/params 0.1.0

package/dist/storage/idb.js

@@ -0,0 +1,119 @@
+// src/storage/idb/index.ts
+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.
+  };
+}
+export {
+  idbStorage
+};
+//# sourceMappingURL=idb.js.map

package/dist/storage/idb.js.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/local.cjs

@@ -0,0 +1,121 @@
+"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/local/index.ts
+var local_exports = {};
+__export(local_exports, {
+  browserStorage: () => browserStorage,
+  localStorage: () => localStorage
+});
+module.exports = __toCommonJS(local_exports);
+var isClient = typeof window !== "undefined";
+function localStorage(options) {
+  return browserStorage("localStorage", options);
+}
+function getStore(kind) {
+  if (!isClient) return void 0;
+  try {
+    return kind === "localStorage" ? window.localStorage : window.sessionStorage;
+  } catch {
+    return void 0;
+  }
+}
+function browserStorage(kind, options) {
+  const serialize = options.serialize ?? JSON.stringify;
+  const deserialize = options.deserialize ?? JSON.parse;
+  const readImpl = () => {
+    const store = getStore(kind);
+    if (!store) return void 0;
+    try {
+      const raw = store.getItem(options.key);
+      if (raw === null) return void 0;
+      const parsed = deserialize(raw);
+      if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return void 0;
+      }
+      return parsed;
+    } catch {
+      return void 0;
+    }
+  };
+  return {
+    name: kind === "localStorage" ? "localStorage" : "sessionStorage",
+    clientOnly: true,
+    read: readImpl,
+    write: (values) => {
+      const store = getStore(kind);
+      if (!store) return;
+      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) {
+          store.removeItem(options.key);
+        } else {
+          store.setItem(options.key, serialize(merged));
+        }
+      } catch {
+      }
+    },
+    clear: (paths) => {
+      const store = getStore(kind);
+      if (!store) return;
+      try {
+        if (paths.length === 0) {
+          store.removeItem(options.key);
+          return;
+        }
+        const existing = readImpl();
+        if (!existing) return;
+        const next = { ...existing };
+        for (const path of paths) delete next[path];
+        if (Object.keys(next).length === 0) {
+          store.removeItem(options.key);
+        } else {
+          store.setItem(options.key, serialize(next));
+        }
+      } catch {
+      }
+    },
+    subscribe: (callback) => {
+      if (!isClient) return () => void 0;
+      const targetStore = getStore(kind);
+      const handler = (event) => {
+        if (event.key !== options.key && event.key !== null) return;
+        if (targetStore && event.storageArea !== targetStore) return;
+        const values = readImpl();
+        if (values) callback(values);
+      };
+      window.addEventListener("storage", handler);
+      return () => window.removeEventListener("storage", handler);
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  browserStorage,
+  localStorage
+});
+//# sourceMappingURL=local.cjs.map

package/dist/storage/local.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/storage/local/index.ts"],"sourcesContent":["import type { ParamsStorage } from '../../storage'\n\nexport interface LocalStorageOptions {\n  /** Storage key the backend owns. */\n  readonly key: string\n  /** Whole-blob serializer. Default: `JSON.stringify`. */\n  readonly serialize?: (values: unknown) => string\n  /** Whole-blob deserializer. Default: `JSON.parse`. */\n  readonly deserialize?: (raw: string) => unknown\n}\n\nconst isClient = typeof window !== 'undefined'\n\n/**\n * `localStorage`-backed storage. Persists managed paths under a single\n * JSON-encoded key. Cross-tab sync via `storage` events.\n *\n * Limitations:\n *  - Same-tab `localStorage.setItem(key, ...)` calls from outside the lib\n *    are not observed (`storage` event doesn't fire for same-tab writes).\n *  - Storage failures (quota, private mode) silently fall back to in-memory.\n */\nexport function localStorage<T = Record<string, unknown>>(\n  options: LocalStorageOptions,\n): ParamsStorage<T> {\n  return browserStorage<T>('localStorage', options)\n}\n\nfunction getStore(kind: 'localStorage' | 'sessionStorage'): Storage | undefined {\n  if (!isClient) return undefined\n  try {\n    return kind === 'localStorage' ? window.localStorage : window.sessionStorage\n  } catch {\n    // Some browsers throw accessing storage in private mode\n    return undefined\n  }\n}\n\nexport function browserStorage<T>(\n  kind: 'localStorage' | 'sessionStorage',\n  options: LocalStorageOptions,\n): ParamsStorage<T> {\n  const serialize = options.serialize ?? JSON.stringify\n  const deserialize = options.deserialize ?? JSON.parse\n\n  const readImpl = (): Partial<T> | undefined => {\n    const store = getStore(kind)\n    if (!store) return undefined\n    try {\n      const raw = store.getItem(options.key)\n      if (raw === null) return undefined\n      const parsed = deserialize(raw)\n      if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {\n        return undefined\n      }\n      return parsed as Partial<T>\n    } catch {\n      return undefined\n    }\n  }\n\n  return {\n    name: kind === 'localStorage' ? 'localStorage' : 'sessionStorage',\n    clientOnly: true,\n    read: readImpl,\n    write: (values) => {\n      const store = getStore(kind)\n      if (!store) return\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          store.removeItem(options.key)\n        } else {\n          store.setItem(options.key, serialize(merged))\n        }\n      } catch {\n        // Quota exceeded / unavailable — silent fallback\n      }\n    },\n    clear: (paths) => {\n      const store = getStore(kind)\n      if (!store) return\n      try {\n        if (paths.length === 0) {\n          store.removeItem(options.key)\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          store.removeItem(options.key)\n        } else {\n          store.setItem(options.key, serialize(next))\n        }\n      } catch {\n        // Silent fallback\n      }\n    },\n    subscribe: (callback) => {\n      if (!isClient) return () => undefined\n      const targetStore = getStore(kind)\n      const handler = (event: StorageEvent) => {\n        // Ignore unrelated keys; null === storage cleared\n        if (event.key !== options.key && event.key !== null) return\n        if (targetStore && event.storageArea !== targetStore) return\n        const values = readImpl()\n        if (values) callback(values)\n      }\n      window.addEventListener('storage', handler)\n      return () => window.removeEventListener('storage', handler)\n    },\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAWA,IAAM,WAAW,OAAO,WAAW;AAW5B,SAAS,aACd,SACkB;AAClB,SAAO,eAAkB,gBAAgB,OAAO;AAClD;AAEA,SAAS,SAAS,MAA8D;AAC9E,MAAI,CAAC,SAAU,QAAO;AACtB,MAAI;AACF,WAAO,SAAS,iBAAiB,OAAO,eAAe,OAAO;AAAA,EAChE,QAAQ;AAEN,WAAO;AAAA,EACT;AACF;AAEO,SAAS,eACd,MACA,SACkB;AAClB,QAAM,YAAY,QAAQ,aAAa,KAAK;AAC5C,QAAM,cAAc,QAAQ,eAAe,KAAK;AAEhD,QAAM,WAAW,MAA8B;AAC7C,UAAM,QAAQ,SAAS,IAAI;AAC3B,QAAI,CAAC,MAAO,QAAO;AACnB,QAAI;AACF,YAAM,MAAM,MAAM,QAAQ,QAAQ,GAAG;AACrC,UAAI,QAAQ,KAAM,QAAO;AACzB,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,SAAS,iBAAiB,iBAAiB;AAAA,IACjD,YAAY;AAAA,IACZ,MAAM;AAAA,IACN,OAAO,CAAC,WAAW;AACjB,YAAM,QAAQ,SAAS,IAAI;AAC3B,UAAI,CAAC,MAAO;AACZ,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,gBAAM,WAAW,QAAQ,GAAG;AAAA,QAC9B,OAAO;AACL,gBAAM,QAAQ,QAAQ,KAAK,UAAU,MAAM,CAAC;AAAA,QAC9C;AAAA,MACF,QAAQ;AAAA,MAER;AAAA,IACF;AAAA,IACA,OAAO,CAAC,UAAU;AAChB,YAAM,QAAQ,SAAS,IAAI;AAC3B,UAAI,CAAC,MAAO;AACZ,UAAI;AACF,YAAI,MAAM,WAAW,GAAG;AACtB,gBAAM,WAAW,QAAQ,GAAG;AAC5B;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,gBAAM,WAAW,QAAQ,GAAG;AAAA,QAC9B,OAAO;AACL,gBAAM,QAAQ,QAAQ,KAAK,UAAU,IAAI,CAAC;AAAA,QAC5C;AAAA,MACF,QAAQ;AAAA,MAER;AAAA,IACF;AAAA,IACA,WAAW,CAAC,aAAa;AACvB,UAAI,CAAC,SAAU,QAAO,MAAM;AAC5B,YAAM,cAAc,SAAS,IAAI;AACjC,YAAM,UAAU,CAAC,UAAwB;AAEvC,YAAI,MAAM,QAAQ,QAAQ,OAAO,MAAM,QAAQ,KAAM;AACrD,YAAI,eAAe,MAAM,gBAAgB,YAAa;AACtD,cAAM,SAAS,SAAS;AACxB,YAAI,OAAQ,UAAS,MAAM;AAAA,MAC7B;AACA,aAAO,iBAAiB,WAAW,OAAO;AAC1C,aAAO,MAAM,OAAO,oBAAoB,WAAW,OAAO;AAAA,IAC5D;AAAA,EACF;AACF;","names":[]}

package/dist/storage/local.d.cts

@@ -0,0 +1,23 @@
+import { P as ParamsStorage } from '../storage-DBLIRR-4.cjs';
+
+interface LocalStorageOptions {
+    /** Storage key the backend owns. */
+    readonly key: string;
+    /** Whole-blob serializer. Default: `JSON.stringify`. */
+    readonly serialize?: (values: unknown) => string;
+    /** Whole-blob deserializer. Default: `JSON.parse`. */
+    readonly deserialize?: (raw: string) => unknown;
+}
+/**
+ * `localStorage`-backed storage. Persists managed paths under a single
+ * JSON-encoded key. Cross-tab sync via `storage` events.
+ *
+ * Limitations:
+ *  - Same-tab `localStorage.setItem(key, ...)` calls from outside the lib
+ *    are not observed (`storage` event doesn't fire for same-tab writes).
+ *  - Storage failures (quota, private mode) silently fall back to in-memory.
+ */
+declare function localStorage<T = Record<string, unknown>>(options: LocalStorageOptions): ParamsStorage<T>;
+declare function browserStorage<T>(kind: 'localStorage' | 'sessionStorage', options: LocalStorageOptions): ParamsStorage<T>;
+
+export { type LocalStorageOptions, browserStorage, localStorage };

package/dist/storage/local.d.ts

@@ -0,0 +1,23 @@
+import { P as ParamsStorage } from '../storage-DBLIRR-4.js';
+
+interface LocalStorageOptions {
+    /** Storage key the backend owns. */
+    readonly key: string;
+    /** Whole-blob serializer. Default: `JSON.stringify`. */
+    readonly serialize?: (values: unknown) => string;
+    /** Whole-blob deserializer. Default: `JSON.parse`. */
+    readonly deserialize?: (raw: string) => unknown;
+}
+/**
+ * `localStorage`-backed storage. Persists managed paths under a single
+ * JSON-encoded key. Cross-tab sync via `storage` events.
+ *
+ * Limitations:
+ *  - Same-tab `localStorage.setItem(key, ...)` calls from outside the lib
+ *    are not observed (`storage` event doesn't fire for same-tab writes).
+ *  - Storage failures (quota, private mode) silently fall back to in-memory.
+ */
+declare function localStorage<T = Record<string, unknown>>(options: LocalStorageOptions): ParamsStorage<T>;
+declare function browserStorage<T>(kind: 'localStorage' | 'sessionStorage', options: LocalStorageOptions): ParamsStorage<T>;
+
+export { type LocalStorageOptions, browserStorage, localStorage };

package/dist/storage/local.js

@@ -0,0 +1,9 @@
+import {
+  browserStorage,
+  localStorage
+} from "../chunk-NHCH2WKC.js";
+export {
+  browserStorage,
+  localStorage
+};
+//# sourceMappingURL=local.js.map

package/dist/storage/local.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/storage/server.cjs

@@ -0,0 +1,158 @@
+"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/server/index.ts
+var server_exports = {};
+__export(server_exports, {
+  serverStorage: () => serverStorage
+});
+module.exports = __toCommonJS(server_exports);
+var RETRY_CAP = 10;
+var DEFAULT_RETRY = 3;
+var MAX_BACKOFF_MS = 5e3;
+function serverStorage(opts) {
+  const name = opts.name ?? "serverStorage";
+  const retryDelay = opts.retryDelay ?? defaultBackoff;
+  let cache;
+  let lastFetchAt = 0;
+  const controllers = /* @__PURE__ */ new Set();
+  const subscribers = /* @__PURE__ */ new Set();
+  let revalidateTimer;
+  const cancelInFlight = () => {
+    for (const c of controllers) c.abort();
+    controllers.clear();
+    if (revalidateTimer !== void 0) {
+      clearTimeout(revalidateTimer);
+      revalidateTimer = void 0;
+    }
+  };
+  const performRead = async () => {
+    const controller = new AbortController();
+    controllers.add(controller);
+    try {
+      const values = await runWithRetry(
+        (signal) => opts.read(signal),
+        controller.signal,
+        opts.retry ?? DEFAULT_RETRY,
+        retryDelay
+      );
+      if (controller.signal.aborted) return void 0;
+      if (values !== void 0) {
+        cache = values;
+        lastFetchAt = Date.now();
+        for (const sub of subscribers) sub(values);
+      }
+      return values ?? void 0;
+    } finally {
+      controllers.delete(controller);
+    }
+  };
+  const scheduleRevalidate = (delayMs) => {
+    if (revalidateTimer !== void 0) return;
+    revalidateTimer = setTimeout(() => {
+      revalidateTimer = void 0;
+      void performRead();
+    }, delayMs);
+  };
+  return {
+    name,
+    clientOnly: false,
+    // Sync read returns the cached snapshot. Returns undefined until the
+    // first successful readAsync — the engine then falls back to defaults.
+    read: () => cache,
+    // Async read with retry + cancellation + optional SWR.
+    readAsync: async () => {
+      const staleTime = opts.staleTime ?? 0;
+      const elapsed = Date.now() - lastFetchAt;
+      if (staleTime > 0 && cache !== void 0 && elapsed < staleTime) {
+        return cache;
+      }
+      if (staleTime > 0 && cache !== void 0 && elapsed >= staleTime) {
+        scheduleRevalidate(0);
+        return cache;
+      }
+      return performRead();
+    },
+    write: async (values) => {
+      await runWithRetry(
+        () => opts.write(values),
+        // Writes are committal — no engine-driven cancellation.
+        new AbortController().signal,
+        opts.retry ?? DEFAULT_RETRY,
+        retryDelay
+      );
+      cache = { ...cache, ...values };
+    },
+    subscribe: (callback) => {
+      subscribers.add(callback);
+      return () => {
+        subscribers.delete(callback);
+        if (subscribers.size === 0) cancelInFlight();
+      };
+    },
+    clear: async () => {
+      cache = void 0;
+      lastFetchAt = 0;
+    }
+  };
+}
+async function runWithRetry(op, signal, retry, retryDelay) {
+  let attempt = 0;
+  let lastError;
+  while (attempt <= RETRY_CAP) {
+    if (signal.aborted) throw new DOMException("aborted", "AbortError");
+    try {
+      return await op(signal);
+    } catch (err) {
+      lastError = err;
+      if (signal.aborted) throw err;
+      const shouldRetry = typeof retry === "number" ? attempt < retry : retry(attempt, err) && attempt < RETRY_CAP;
+      if (!shouldRetry) throw err;
+      const delay = Math.min(retryDelay(attempt), MAX_BACKOFF_MS);
+      await sleep(delay, signal);
+      attempt++;
+    }
+  }
+  throw lastError;
+}
+function defaultBackoff(attempt) {
+  return Math.min(100 * 2 ** attempt, MAX_BACKOFF_MS);
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) {
+      reject(new DOMException("aborted", "AbortError"));
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new DOMException("aborted", "AbortError"));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  serverStorage
+});
+//# sourceMappingURL=server.cjs.map

package/dist/storage/server.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/storage/server/index.ts"],"sourcesContent":["import type { ParamsStorage } from '../../storage'\n\nexport interface ServerStorageOptions<T> {\n  /**\n   * Async fetch; returns the latest server values or undefined. Closure-bound\n   * at factory time. Receives an `AbortSignal` so the consumer's HTTP client\n   * can short-circuit when the store is disposed mid-flight.\n   */\n  read: (signal: AbortSignal) => Promise<Partial<T> | undefined>\n\n  /**\n   * Async write; throws on failure. The engine catches the throw and silently\n   * falls back to in-memory state — the standard storage error contract.\n   */\n  write: (values: Partial<T>) => Promise<void>\n\n  /**\n   * Stale-while-revalidate window in ms. When > 0, `readAsync` returns the\n   * cached snapshot immediately and revalidates in the background after this\n   * many ms have elapsed since the last successful read.\n   *\n   * Default: 0 (no SWR — every readAsync hits the wire).\n   */\n  staleTime?: number\n\n  /**\n   * Retry policy. Number of retries on read/write failure, OR a predicate\n   * receiving `(attempt, error)` returning `true` to retry. Default: 3.\n   * Capped at 10 internally regardless of predicate behavior.\n   */\n  retry?: number | ((attempt: number, error: unknown) => boolean)\n\n  /**\n   * Backoff delay (ms) for the Nth retry (0-indexed: attempt 0 = first retry).\n   * Default: exponential `100 * 2^attempt`, capped at 5000.\n   */\n  retryDelay?: (attempt: number) => number\n\n  /** Diagnostics name. Default: 'serverStorage'. */\n  name?: string\n}\n\nconst RETRY_CAP = 10\nconst DEFAULT_RETRY = 3\nconst MAX_BACKOFF_MS = 5000\n\n/**\n * Server-state backed storage. Pair an async `read`/`write` adapter (your\n * HTTP client of choice) with built-in retry, AbortController cancellation,\n * and optional stale-while-revalidate semantics.\n *\n * Use cases:\n *  - User-account-tied app config (theme + locale stored on the server).\n *  - Saved filter views, pinned dashboards, etc.\n *  - Anything that should round-trip through your API on every change.\n *\n * For high-frequency state (filters, search), prefer `urlStorage`. Server\n * storage shines when the values must persist across devices.\n *\n * Cancellation: when the params store disposes, the subscribe cleanup runs\n * and aborts any in-flight `readAsync` via the signal threaded into the\n * consumer's `read()` adapter. Wire the signal through your fetch call to\n * get full short-circuit behavior.\n */\nexport function serverStorage<T>(opts: ServerStorageOptions<T>): ParamsStorage<T> {\n  const name = opts.name ?? 'serverStorage'\n  const retryDelay = opts.retryDelay ?? defaultBackoff\n  let cache: Partial<T> | undefined\n  let lastFetchAt = 0\n  const controllers = new Set<AbortController>()\n  const subscribers = new Set<(values: Partial<T>) => void>()\n  let revalidateTimer: ReturnType<typeof setTimeout> | undefined\n\n  const cancelInFlight = (): void => {\n    for (const c of controllers) c.abort()\n    controllers.clear()\n    if (revalidateTimer !== undefined) {\n      clearTimeout(revalidateTimer)\n      revalidateTimer = undefined\n    }\n  }\n\n  const performRead = async (): Promise<Partial<T> | undefined> => {\n    const controller = new AbortController()\n    controllers.add(controller)\n    try {\n      const values = await runWithRetry(\n        (signal) => opts.read(signal),\n        controller.signal,\n        opts.retry ?? DEFAULT_RETRY,\n        retryDelay,\n      )\n      if (controller.signal.aborted) return undefined\n      if (values !== undefined) {\n        cache = values\n        lastFetchAt = Date.now()\n        for (const sub of subscribers) sub(values)\n      }\n      return values ?? undefined\n    } finally {\n      controllers.delete(controller)\n    }\n  }\n\n  const scheduleRevalidate = (delayMs: number): void => {\n    if (revalidateTimer !== undefined) return\n    revalidateTimer = setTimeout(() => {\n      revalidateTimer = undefined\n      void performRead()\n    }, delayMs)\n  }\n\n  return {\n    name,\n    clientOnly: false,\n\n    // Sync read returns the cached snapshot. Returns undefined until the\n    // first successful readAsync — the engine then falls back to defaults.\n    read: () => cache,\n\n    // Async read with retry + cancellation + optional SWR.\n    readAsync: async () => {\n      const staleTime = opts.staleTime ?? 0\n      const elapsed = Date.now() - lastFetchAt\n      // SWR fast path: cache is fresh, return it without hitting the wire.\n      if (staleTime > 0 && cache !== undefined && elapsed < staleTime) {\n        return cache\n      }\n      // SWR background path: cache is stale but present — return it,\n      // schedule a background revalidation.\n      if (staleTime > 0 && cache !== undefined && elapsed >= staleTime) {\n        scheduleRevalidate(0)\n        return cache\n      }\n      // Cold path: no cache yet, must wait for the read.\n      return performRead()\n    },\n\n    write: async (values) => {\n      await runWithRetry(\n        () => opts.write(values),\n        // Writes are committal — no engine-driven cancellation.\n        new AbortController().signal,\n        opts.retry ?? DEFAULT_RETRY,\n        retryDelay,\n      )\n      // Optimistic cache update so subsequent sync reads see the new values\n      // without waiting for a server round-trip.\n      cache = { ...cache, ...values }\n    },\n\n    subscribe: (callback) => {\n      subscribers.add(callback)\n      return () => {\n        subscribers.delete(callback)\n        // When the LAST subscriber unsubscribes (typical: store disposes),\n        // abort in-flight reads + cancel any pending revalidation.\n        if (subscribers.size === 0) cancelInFlight()\n      }\n    },\n\n    clear: async () => {\n      // Reset cache; consumers can choose to also call write({}) to wipe\n      // the server state — that's a higher-level decision.\n      cache = undefined\n      lastFetchAt = 0\n    },\n  }\n}\n\n/**\n * Run an async operation with retry + abort. The signal short-circuits both\n * the in-flight call and the inter-attempt backoff sleeps.\n */\nasync function runWithRetry<R>(\n  op: (signal: AbortSignal) => Promise<R>,\n  signal: AbortSignal,\n  retry: number | ((attempt: number, error: unknown) => boolean),\n  retryDelay: (attempt: number) => number,\n): Promise<R> {\n  let attempt = 0\n  let lastError: unknown\n  while (attempt <= RETRY_CAP) {\n    if (signal.aborted) throw new DOMException('aborted', 'AbortError')\n    try {\n      return await op(signal)\n    } catch (err) {\n      lastError = err\n      if (signal.aborted) throw err\n      const shouldRetry =\n        typeof retry === 'number' ? attempt < retry : retry(attempt, err) && attempt < RETRY_CAP\n      if (!shouldRetry) throw err\n      const delay = Math.min(retryDelay(attempt), MAX_BACKOFF_MS)\n      await sleep(delay, signal)\n      attempt++\n    }\n  }\n  throw lastError\n}\n\nfunction defaultBackoff(attempt: number): number {\n  return Math.min(100 * 2 ** attempt, MAX_BACKOFF_MS)\n}\n\nfunction sleep(ms: number, signal: AbortSignal): Promise<void> {\n  return new Promise<void>((resolve, reject) => {\n    if (signal.aborted) {\n      reject(new DOMException('aborted', 'AbortError'))\n      return\n    }\n    const timer = setTimeout(() => {\n      signal.removeEventListener('abort', onAbort)\n      resolve()\n    }, ms)\n    const onAbort = (): void => {\n      clearTimeout(timer)\n      reject(new DOMException('aborted', 'AbortError'))\n    }\n    signal.addEventListener('abort', onAbort, { once: true })\n  })\n}\n"],"mappings":"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","names":[]}

package/dist/storage/server.d.cts

@@ -0,0 +1,57 @@
+import { P as ParamsStorage } from '../storage-DBLIRR-4.cjs';
+
+interface ServerStorageOptions<T> {
+    /**
+     * Async fetch; returns the latest server values or undefined. Closure-bound
+     * at factory time. Receives an `AbortSignal` so the consumer's HTTP client
+     * can short-circuit when the store is disposed mid-flight.
+     */
+    read: (signal: AbortSignal) => Promise<Partial<T> | undefined>;
+    /**
+     * Async write; throws on failure. The engine catches the throw and silently
+     * falls back to in-memory state — the standard storage error contract.
+     */
+    write: (values: Partial<T>) => Promise<void>;
+    /**
+     * Stale-while-revalidate window in ms. When > 0, `readAsync` returns the
+     * cached snapshot immediately and revalidates in the background after this
+     * many ms have elapsed since the last successful read.
+     *
+     * Default: 0 (no SWR — every readAsync hits the wire).
+     */
+    staleTime?: number;
+    /**
+     * Retry policy. Number of retries on read/write failure, OR a predicate
+     * receiving `(attempt, error)` returning `true` to retry. Default: 3.
+     * Capped at 10 internally regardless of predicate behavior.
+     */
+    retry?: number | ((attempt: number, error: unknown) => boolean);
+    /**
+     * Backoff delay (ms) for the Nth retry (0-indexed: attempt 0 = first retry).
+     * Default: exponential `100 * 2^attempt`, capped at 5000.
+     */
+    retryDelay?: (attempt: number) => number;
+    /** Diagnostics name. Default: 'serverStorage'. */
+    name?: string;
+}
+/**
+ * Server-state backed storage. Pair an async `read`/`write` adapter (your
+ * HTTP client of choice) with built-in retry, AbortController cancellation,
+ * and optional stale-while-revalidate semantics.
+ *
+ * Use cases:
+ *  - User-account-tied app config (theme + locale stored on the server).
+ *  - Saved filter views, pinned dashboards, etc.
+ *  - Anything that should round-trip through your API on every change.
+ *
+ * For high-frequency state (filters, search), prefer `urlStorage`. Server
+ * storage shines when the values must persist across devices.
+ *
+ * Cancellation: when the params store disposes, the subscribe cleanup runs
+ * and aborts any in-flight `readAsync` via the signal threaded into the
+ * consumer's `read()` adapter. Wire the signal through your fetch call to
+ * get full short-circuit behavior.
+ */
+declare function serverStorage<T>(opts: ServerStorageOptions<T>): ParamsStorage<T>;
+
+export { type ServerStorageOptions, serverStorage };

package/dist/storage/server.d.ts

@@ -0,0 +1,57 @@
+import { P as ParamsStorage } from '../storage-DBLIRR-4.js';
+
+interface ServerStorageOptions<T> {
+    /**
+     * Async fetch; returns the latest server values or undefined. Closure-bound
+     * at factory time. Receives an `AbortSignal` so the consumer's HTTP client
+     * can short-circuit when the store is disposed mid-flight.
+     */
+    read: (signal: AbortSignal) => Promise<Partial<T> | undefined>;
+    /**
+     * Async write; throws on failure. The engine catches the throw and silently
+     * falls back to in-memory state — the standard storage error contract.
+     */
+    write: (values: Partial<T>) => Promise<void>;
+    /**
+     * Stale-while-revalidate window in ms. When > 0, `readAsync` returns the
+     * cached snapshot immediately and revalidates in the background after this
+     * many ms have elapsed since the last successful read.
+     *
+     * Default: 0 (no SWR — every readAsync hits the wire).
+     */
+    staleTime?: number;
+    /**
+     * Retry policy. Number of retries on read/write failure, OR a predicate
+     * receiving `(attempt, error)` returning `true` to retry. Default: 3.
+     * Capped at 10 internally regardless of predicate behavior.
+     */
+    retry?: number | ((attempt: number, error: unknown) => boolean);
+    /**
+     * Backoff delay (ms) for the Nth retry (0-indexed: attempt 0 = first retry).
+     * Default: exponential `100 * 2^attempt`, capped at 5000.
+     */
+    retryDelay?: (attempt: number) => number;
+    /** Diagnostics name. Default: 'serverStorage'. */
+    name?: string;
+}
+/**
+ * Server-state backed storage. Pair an async `read`/`write` adapter (your
+ * HTTP client of choice) with built-in retry, AbortController cancellation,
+ * and optional stale-while-revalidate semantics.
+ *
+ * Use cases:
+ *  - User-account-tied app config (theme + locale stored on the server).
+ *  - Saved filter views, pinned dashboards, etc.
+ *  - Anything that should round-trip through your API on every change.
+ *
+ * For high-frequency state (filters, search), prefer `urlStorage`. Server
+ * storage shines when the values must persist across devices.
+ *
+ * Cancellation: when the params store disposes, the subscribe cleanup runs
+ * and aborts any in-flight `readAsync` via the signal threaded into the
+ * consumer's `read()` adapter. Wire the signal through your fetch call to
+ * get full short-circuit behavior.
+ */
+declare function serverStorage<T>(opts: ServerStorageOptions<T>): ParamsStorage<T>;
+
+export { type ServerStorageOptions, serverStorage };