@victorylabs/params 0.1.0

package/dist/storage/server.js

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

package/dist/storage/server.js.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/session.cjs

@@ -0,0 +1,123 @@
+"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/session/index.ts
+var session_exports = {};
+__export(session_exports, {
+  sessionStorage: () => sessionStorage
+});
+module.exports = __toCommonJS(session_exports);
+
+// src/storage/local/index.ts
+var isClient = typeof window !== "undefined";
+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);
+    }
+  };
+}
+
+// src/storage/session/index.ts
+function sessionStorage(options) {
+  return browserStorage("sessionStorage", options);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  sessionStorage
+});
+//# sourceMappingURL=session.cjs.map

package/dist/storage/session.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/storage/session/index.ts","../../src/storage/local/index.ts"],"sourcesContent":["import type { ParamsStorage } from '../../storage'\nimport type { LocalStorageOptions } from '../local'\nimport { browserStorage } from '../local'\n\nexport type { LocalStorageOptions as SessionStorageOptions } from '../local'\n\n/**\n * `sessionStorage`-backed storage. Same shape as `localStorage` but scoped\n * to the current tab/session — values clear when the tab closes.\n *\n * Cross-tab sync works through `storage` events (browsers fire them for\n * sessionStorage updates within the same origin), but the data itself is\n * tab-scoped — opening the URL in a new tab starts fresh.\n */\nexport function sessionStorage<T = Record<string, unknown>>(\n  options: LocalStorageOptions,\n): ParamsStorage<T> {\n  return browserStorage<T>('sessionStorage', options)\n}\n","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;;;ACWA,IAAM,WAAW,OAAO,WAAW;AAiBnC,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;;;AD5GO,SAAS,eACd,SACkB;AAClB,SAAO,eAAkB,kBAAkB,OAAO;AACpD;","names":[]}

package/dist/storage/session.d.cts

@@ -0,0 +1,14 @@
+import { P as ParamsStorage } from '../storage-DBLIRR-4.cjs';
+import { LocalStorageOptions } from './local.cjs';
+
+/**
+ * `sessionStorage`-backed storage. Same shape as `localStorage` but scoped
+ * to the current tab/session — values clear when the tab closes.
+ *
+ * Cross-tab sync works through `storage` events (browsers fire them for
+ * sessionStorage updates within the same origin), but the data itself is
+ * tab-scoped — opening the URL in a new tab starts fresh.
+ */
+declare function sessionStorage<T = Record<string, unknown>>(options: LocalStorageOptions): ParamsStorage<T>;
+
+export { LocalStorageOptions as SessionStorageOptions, sessionStorage };

package/dist/storage/session.d.ts

@@ -0,0 +1,14 @@
+import { P as ParamsStorage } from '../storage-DBLIRR-4.js';
+import { LocalStorageOptions } from './local.js';
+
+/**
+ * `sessionStorage`-backed storage. Same shape as `localStorage` but scoped
+ * to the current tab/session — values clear when the tab closes.
+ *
+ * Cross-tab sync works through `storage` events (browsers fire them for
+ * sessionStorage updates within the same origin), but the data itself is
+ * tab-scoped — opening the URL in a new tab starts fresh.
+ */
+declare function sessionStorage<T = Record<string, unknown>>(options: LocalStorageOptions): ParamsStorage<T>;
+
+export { LocalStorageOptions as SessionStorageOptions, sessionStorage };

package/dist/storage/session.js

@@ -0,0 +1,12 @@
+import {
+  browserStorage
+} from "../chunk-NHCH2WKC.js";
+
+// src/storage/session/index.ts
+function sessionStorage(options) {
+  return browserStorage("sessionStorage", options);
+}
+export {
+  sessionStorage
+};
+//# sourceMappingURL=session.js.map

package/dist/storage/session.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/storage/session/index.ts"],"sourcesContent":["import type { ParamsStorage } from '../../storage'\nimport type { LocalStorageOptions } from '../local'\nimport { browserStorage } from '../local'\n\nexport type { LocalStorageOptions as SessionStorageOptions } from '../local'\n\n/**\n * `sessionStorage`-backed storage. Same shape as `localStorage` but scoped\n * to the current tab/session — values clear when the tab closes.\n *\n * Cross-tab sync works through `storage` events (browsers fire them for\n * sessionStorage updates within the same origin), but the data itself is\n * tab-scoped — opening the URL in a new tab starts fresh.\n */\nexport function sessionStorage<T = Record<string, unknown>>(\n  options: LocalStorageOptions,\n): ParamsStorage<T> {\n  return browserStorage<T>('sessionStorage', options)\n}\n"],"mappings":";;;;;AAcO,SAAS,eACd,SACkB;AAClB,SAAO,eAAkB,kBAAkB,OAAO;AACpD;","names":[]}

package/dist/storage/url.cjs

@@ -0,0 +1,132 @@
+"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/url/index.ts
+var url_exports = {};
+__export(url_exports, {
+  urlStorage: () => urlStorage
+});
+module.exports = __toCommonJS(url_exports);
+
+// src/schema.ts
+function defaultSerialize(value) {
+  if (value === void 0 || value === null) return "";
+  if (typeof value === "string") return value;
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number") return Number.isFinite(value) ? String(value) : "";
+  return JSON.stringify(value);
+}
+
+// src/storage/url/index.ts
+var isClient = typeof window !== "undefined";
+function urlStorage(options = {}) {
+  const adapterStrategy = options.strategy ?? "replace";
+  const paramMap = options.paramMap ?? {};
+  const reverseMap = buildReverseMap(paramMap);
+  const serialize = options.serialize ?? {};
+  const deserialize = options.deserialize ?? {};
+  const readImpl = () => {
+    if (!isClient) return void 0;
+    try {
+      const params = new URLSearchParams(window.location.search);
+      const partial = {};
+      let hasAny = false;
+      for (const [paramKey, raw] of params.entries()) {
+        const formPath = reverseMap[paramKey] ?? paramKey;
+        const deserializer = deserialize[formPath];
+        try {
+          partial[formPath] = deserializer ? deserializer(raw) : raw;
+          hasAny = true;
+        } catch {
+        }
+      }
+      return hasAny ? partial : void 0;
+    } catch {
+      return void 0;
+    }
+  };
+  const updateUrl = (params, opts) => {
+    if (!isClient) return;
+    const search = params.toString();
+    const url = search ? `${window.location.pathname}?${search}` : window.location.pathname;
+    const strategy = opts?.history ?? adapterStrategy;
+    try {
+      if (strategy === "push") {
+        window.history.pushState(null, "", url);
+      } else {
+        window.history.replaceState(null, "", url);
+      }
+    } catch {
+    }
+  };
+  return {
+    name: "urlStorage",
+    clientOnly: true,
+    read: readImpl,
+    write: (values, _changed, opts) => {
+      if (!isClient) return;
+      const params = new URLSearchParams(window.location.search);
+      for (const [path, value] of Object.entries(values)) {
+        const paramKey = paramMap[path] ?? path;
+        if (value === void 0 || value === null) {
+          params.delete(paramKey);
+          continue;
+        }
+        const serializer = serialize[path];
+        const str = serializer ? serializer(value) : defaultSerialize(value);
+        params.set(paramKey, str);
+      }
+      updateUrl(params, opts);
+    },
+    clear: (paths, opts) => {
+      if (!isClient) return;
+      if (paths.length === 0) {
+        updateUrl(new URLSearchParams(), opts);
+        return;
+      }
+      const params = new URLSearchParams(window.location.search);
+      for (const path of paths) {
+        const paramKey = paramMap[path] ?? path;
+        params.delete(paramKey);
+      }
+      updateUrl(params, opts);
+    },
+    subscribe: (callback) => {
+      if (!isClient) return () => void 0;
+      const handler = () => {
+        const values = readImpl();
+        if (values) callback(values);
+      };
+      window.addEventListener("popstate", handler);
+      return () => window.removeEventListener("popstate", handler);
+    }
+  };
+}
+function buildReverseMap(map) {
+  const reverse = {};
+  for (const [formPath, paramKey] of Object.entries(map)) {
+    reverse[paramKey] = formPath;
+  }
+  return reverse;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  urlStorage
+});
+//# sourceMappingURL=url.cjs.map

package/dist/storage/url.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/storage/url/index.ts","../../src/schema.ts"],"sourcesContent":["import { defaultSerialize } from '../../schema'\nimport type { ParamsStorage, WriteOptions } from '../../storage'\n\nexport interface UrlStorageOptions {\n  /**\n   * History API strategy. `'replace'` keeps the back-stack clean (recommended\n   * for filters/search). `'push'` creates a new history entry for every write.\n   * Default: `'replace'`.\n   */\n  readonly strategy?: 'replace' | 'push'\n\n  /** form path → URL search-param key. Defaults to identity. */\n  readonly paramMap?: Record<string, string>\n\n  /** Per-path string serializer. Default: `defaultSerialize` (same as schema). */\n  readonly serialize?: Record<string, (value: unknown) => string>\n\n  /** Per-path string-to-value deserializer. Default: identity (raw string). */\n  readonly deserialize?: Record<string, (str: string) => unknown>\n}\n\nconst isClient = typeof window !== 'undefined'\n\n/**\n * URL search-param storage backend (native History API).\n *\n * - Hydrates from `window.location.search` on store creation.\n * - Reflects writes back to the URL via `replaceState` (default) or `pushState`.\n * - Subscribes to `popstate` so back/forward navigation flows into the store.\n *\n * `omitWhenDefault` is honored at the engine level (the store sends `undefined`\n * for paths at default; the backend deletes them from the URL).\n *\n * Limitations (v0.1):\n *  - History API only — `hashchange` not supported.\n *  - Cross-tab URL sync not supported (History API is per-tab).\n *\n * v0.4: per-call strategy override via `WriteOptions.history` — store callers\n * can pass `params.set(path, value, { history: 'push' })` to override the\n * adapter-level default for that single write.\n */\nexport function urlStorage<T = Record<string, unknown>>(\n  options: UrlStorageOptions = {},\n): ParamsStorage<T> {\n  const adapterStrategy = options.strategy ?? 'replace'\n  const paramMap = options.paramMap ?? {}\n  const reverseMap = buildReverseMap(paramMap)\n  const serialize = options.serialize ?? {}\n  const deserialize = options.deserialize ?? {}\n\n  const readImpl = (): Partial<T> | undefined => {\n    if (!isClient) return undefined\n    try {\n      const params = new URLSearchParams(window.location.search)\n      const partial: Record<string, unknown> = {}\n      let hasAny = false\n      for (const [paramKey, raw] of params.entries()) {\n        const formPath = reverseMap[paramKey] ?? paramKey\n        const deserializer = deserialize[formPath]\n        try {\n          partial[formPath] = deserializer ? deserializer(raw) : raw\n          hasAny = true\n        } catch {\n          // Per-path deserialize failure → skip; engine falls back to default\n        }\n      }\n      return hasAny ? (partial as Partial<T>) : undefined\n    } catch {\n      return undefined\n    }\n  }\n\n  const updateUrl = (params: URLSearchParams, opts?: WriteOptions): void => {\n    if (!isClient) return\n    const search = params.toString()\n    const url = search ? `${window.location.pathname}?${search}` : window.location.pathname\n    const strategy = opts?.history ?? adapterStrategy\n    try {\n      if (strategy === 'push') {\n        window.history.pushState(null, '', url)\n      } else {\n        window.history.replaceState(null, '', url)\n      }\n    } catch {\n      // Some browsers cap History API writes (rare) — silent fallback.\n    }\n  }\n\n  return {\n    name: 'urlStorage',\n    clientOnly: true,\n    read: readImpl,\n    write: (values, _changed, opts) => {\n      if (!isClient) return\n      const params = new URLSearchParams(window.location.search)\n      for (const [path, value] of Object.entries(values as Record<string, unknown>)) {\n        const paramKey = paramMap[path] ?? path\n        if (value === undefined || value === null) {\n          params.delete(paramKey)\n          continue\n        }\n        const serializer = serialize[path]\n        const str = serializer ? serializer(value) : defaultSerialize(value)\n        params.set(paramKey, str)\n      }\n      updateUrl(params, opts)\n    },\n    clear: (paths, opts) => {\n      if (!isClient) return\n      if (paths.length === 0) {\n        updateUrl(new URLSearchParams(), opts)\n        return\n      }\n      const params = new URLSearchParams(window.location.search)\n      for (const path of paths) {\n        const paramKey = paramMap[path] ?? path\n        params.delete(paramKey)\n      }\n      updateUrl(params, opts)\n    },\n    subscribe: (callback) => {\n      if (!isClient) return () => undefined\n      const handler = () => {\n        const values = readImpl()\n        if (values) callback(values)\n      }\n      window.addEventListener('popstate', handler)\n      return () => window.removeEventListener('popstate', handler)\n    },\n  }\n}\n\nfunction buildReverseMap(map: Record<string, string>): Record<string, string> {\n  const reverse: Record<string, string> = {}\n  for (const [formPath, paramKey] of Object.entries(map)) {\n    reverse[paramKey] = formPath\n  }\n  return reverse\n}\n","import type { StandardSchemaV1 } from '@standard-schema/spec'\n\nimport type { FieldSpec, PlainFieldSpec } from './types'\n\nexport function isStandardSchema(spec: unknown): spec is StandardSchemaV1 {\n  return (\n    typeof spec === 'object' &&\n    spec !== null &&\n    '~standard' in spec &&\n    typeof (spec as { '~standard'?: unknown })['~standard'] === 'object'\n  )\n}\n\nexport function isPlainSpec<T>(spec: FieldSpec<T>): spec is PlainFieldSpec<T> {\n  return !isStandardSchema(spec) && typeof spec === 'object' && spec !== null && 'default' in spec\n}\n\n/**\n * Resolve a field's default value.\n *\n * - Plain spec: `spec.default` (always present — required by the type).\n * - Standard Schema (Zod, Valibot, ArkType, …): parse `undefined` and use the\n *   schema's `.default()` if it produced a value. Schemas without a default\n *   return `undefined`.\n */\nexport function getDefault<T>(spec: FieldSpec<T>): T | undefined {\n  if (isStandardSchema(spec)) {\n    const result = spec['~standard'].validate(undefined)\n    if (result instanceof Promise) return undefined\n    if ('value' in result && !result.issues) return result.value as T\n    return undefined\n  }\n  return (spec as PlainFieldSpec<T>).default\n}\n\n/**\n * Parse a raw storage value through the field's spec. Returns the typed value\n * on success, or `undefined` on parse failure (engine falls back to default).\n *\n * The engine records the failure reason in `ParamsStore.storageErrors` for\n * debugging; consumer code doesn't see it.\n */\nexport interface ParseResult<T> {\n  ok: boolean\n  value?: T\n  reason?: string\n}\n\nexport function parseField<T>(spec: FieldSpec<T>, raw: unknown): ParseResult<T> {\n  if (isStandardSchema(spec)) {\n    const result = spec['~standard'].validate(raw)\n    if (result instanceof Promise) {\n      return { ok: false, reason: 'async-schema-not-supported-in-v0.1' }\n    }\n    if ('value' in result && !result.issues) return { ok: true, value: result.value as T }\n    return { ok: false, reason: result.issues?.[0]?.message ?? 'parse-failed' }\n  }\n\n  const plainSpec = spec as PlainFieldSpec<T>\n  if (typeof raw === 'string' && plainSpec.parse) {\n    try {\n      return { ok: true, value: plainSpec.parse(raw) }\n    } catch (err) {\n      return { ok: false, reason: err instanceof Error ? err.message : String(err) }\n    }\n  }\n  // No custom parse: accept raw value as-is if it's a usable runtime value\n  // (string, number, boolean, array, object, etc.). The schema-less plain spec\n  // is mostly used for non-string-coerced flows (memory storage with raw values).\n  if (raw === undefined) return { ok: false, reason: 'undefined-no-parse' }\n  return { ok: true, value: raw as T }\n}\n\n/**\n * Serialize a typed value to its storage string representation. Used by URL\n * storage (every value must be a string) and other string-keyed backends.\n *\n * Plain spec uses its `serialize` if provided, else `String(value)`. Standard\n * schemas don't define an inverse — we fall back to `String(value)` (or\n * `JSON.stringify` for objects) and the consumer can override via per-field\n * `serialize` in the storage backend's options.\n */\nexport function defaultSerialize(value: unknown): string {\n  if (value === undefined || value === null) return ''\n  if (typeof value === 'string') return value\n  if (typeof value === 'boolean') return value ? 'true' : 'false'\n  if (typeof value === 'number') return Number.isFinite(value) ? String(value) : ''\n  return JSON.stringify(value)\n}\n\n/**\n * Extract the enum values from a field spec, if any. Returns the array of\n * enum members or `undefined` if the spec doesn't expose them.\n *\n * Supports:\n * - Zod `z.enum(['a', 'b'])` — reads `_def.values: ['a', 'b']`.\n * - Zod `z.nativeEnum(MyEnum)` — reads `_def.values: <enum-object>`.\n *   For numeric enums (TypeScript bidirectional `enum Color { Red = 0 }`),\n *   `Object.values` returns BOTH the numbers and the reverse-mapped strings;\n *   this helper detects the case and filters to numeric values only.\n *\n * Standard Schema doesn't define a uniform enum-introspection API, so libraries\n * other than Zod return `undefined` here — `cycle()` then throws and asks the\n * caller to pass options explicitly.\n */\nexport function extractEnumValues(spec: unknown): readonly unknown[] | undefined {\n  // Walk Zod wrapper types (ZodDefault, ZodOptional, ZodNullable, …) to find\n  // an underlying enum. `.default(...)` / `.optional()` / `.nullable()` produce\n  // a wrapper whose `_def.innerType` points to the wrapped schema. Cap the walk\n  // at a small depth — pathological self-referential schemas shouldn't loop.\n  // biome-ignore lint/suspicious/noExplicitAny: Zod internal `_def` API\n  let current: any = spec\n  for (let i = 0; i < 8 && current !== null && typeof current === 'object'; i++) {\n    const def = current._def\n    if (!def) return undefined\n\n    // z.enum(['a', 'b']): values is already a clean string array.\n    if (Array.isArray(def.values)) return def.values\n\n    // z.nativeEnum(MyEnum): values is the enum object. TS numeric enums are\n    // BIDIRECTIONAL — Object.values returns numbers + reverse-mapped strings:\n    //   enum Color { Red = 0 } → Object.values(Color) = [0, 'Red'].\n    // Detect numeric and filter; pure string enums are unidirectional and\n    // return only strings.\n    if (typeof def.values === 'object' && def.values !== null) {\n      const all = Object.values(def.values)\n      const hasNumber = all.some((v) => typeof v === 'number')\n      return hasNumber ? all.filter((v) => typeof v === 'number') : all\n    }\n\n    if (def.innerType) {\n      current = def.innerType\n      continue\n    }\n    return undefined\n  }\n  return undefined\n}\n"],"mappings":"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","names":[]}

package/dist/storage/url.d.cts

@@ -0,0 +1,37 @@
+import { P as ParamsStorage } from '../storage-DBLIRR-4.cjs';
+
+interface UrlStorageOptions {
+    /**
+     * History API strategy. `'replace'` keeps the back-stack clean (recommended
+     * for filters/search). `'push'` creates a new history entry for every write.
+     * Default: `'replace'`.
+     */
+    readonly strategy?: 'replace' | 'push';
+    /** form path → URL search-param key. Defaults to identity. */
+    readonly paramMap?: Record<string, string>;
+    /** Per-path string serializer. Default: `defaultSerialize` (same as schema). */
+    readonly serialize?: Record<string, (value: unknown) => string>;
+    /** Per-path string-to-value deserializer. Default: identity (raw string). */
+    readonly deserialize?: Record<string, (str: string) => unknown>;
+}
+/**
+ * URL search-param storage backend (native History API).
+ *
+ * - Hydrates from `window.location.search` on store creation.
+ * - Reflects writes back to the URL via `replaceState` (default) or `pushState`.
+ * - Subscribes to `popstate` so back/forward navigation flows into the store.
+ *
+ * `omitWhenDefault` is honored at the engine level (the store sends `undefined`
+ * for paths at default; the backend deletes them from the URL).
+ *
+ * Limitations (v0.1):
+ *  - History API only — `hashchange` not supported.
+ *  - Cross-tab URL sync not supported (History API is per-tab).
+ *
+ * v0.4: per-call strategy override via `WriteOptions.history` — store callers
+ * can pass `params.set(path, value, { history: 'push' })` to override the
+ * adapter-level default for that single write.
+ */
+declare function urlStorage<T = Record<string, unknown>>(options?: UrlStorageOptions): ParamsStorage<T>;
+
+export { type UrlStorageOptions, urlStorage };

package/dist/storage/url.d.ts

@@ -0,0 +1,37 @@
+import { P as ParamsStorage } from '../storage-DBLIRR-4.js';
+
+interface UrlStorageOptions {
+    /**
+     * History API strategy. `'replace'` keeps the back-stack clean (recommended
+     * for filters/search). `'push'` creates a new history entry for every write.
+     * Default: `'replace'`.
+     */
+    readonly strategy?: 'replace' | 'push';
+    /** form path → URL search-param key. Defaults to identity. */
+    readonly paramMap?: Record<string, string>;
+    /** Per-path string serializer. Default: `defaultSerialize` (same as schema). */
+    readonly serialize?: Record<string, (value: unknown) => string>;
+    /** Per-path string-to-value deserializer. Default: identity (raw string). */
+    readonly deserialize?: Record<string, (str: string) => unknown>;
+}
+/**
+ * URL search-param storage backend (native History API).
+ *
+ * - Hydrates from `window.location.search` on store creation.
+ * - Reflects writes back to the URL via `replaceState` (default) or `pushState`.
+ * - Subscribes to `popstate` so back/forward navigation flows into the store.
+ *
+ * `omitWhenDefault` is honored at the engine level (the store sends `undefined`
+ * for paths at default; the backend deletes them from the URL).
+ *
+ * Limitations (v0.1):
+ *  - History API only — `hashchange` not supported.
+ *  - Cross-tab URL sync not supported (History API is per-tab).
+ *
+ * v0.4: per-call strategy override via `WriteOptions.history` — store callers
+ * can pass `params.set(path, value, { history: 'push' })` to override the
+ * adapter-level default for that single write.
+ */
+declare function urlStorage<T = Record<string, unknown>>(options?: UrlStorageOptions): ParamsStorage<T>;
+
+export { type UrlStorageOptions, urlStorage };