@victorylabs/params 0.1.0

package/dist/snapshot.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/snapshot.ts","../src/name-registry.ts"],"sourcesContent":["import { getDefByName, setPreHydrationValues } from './name-registry'\nimport type { ParamsDefinition } from './types'\n\n/**\n * Snapshot keyed by definition name. Returned from `paramsSnapshot()` and\n * accepted by `hydrateParams()` — round-trip transport for SSR.\n */\nexport type ParamsSnapshot = Record<string, unknown>\n\n/**\n * Server-side: produce a snapshot of the current values for the given\n * definitions, keyed by `def.name`. The returned object is JSON-serializable\n * (call `JSON.stringify` to embed in HTML, or pass through your framework's\n * data-loader contract).\n *\n * Each definition MUST have a `name` set (added in v0.1 for forward-compat,\n * load-bearing in v0.2). Throws otherwise.\n *\n * Throws on duplicate names — the snapshot keys would collide.\n *\n * Reads via the synchronous `def.storage.read()` path. Definitions backed by\n * an async-only backend (sync `read()` returns undefined) snapshot as\n * defaults; pair them with a server-side prefetch step before calling\n * `paramsSnapshot()` if you want their fetched values in the snapshot.\n */\nexport function paramsSnapshot(defs: readonly ParamsDefinition[]): ParamsSnapshot {\n  const out: ParamsSnapshot = {}\n  const seenNames = new Set<string>()\n\n  for (const def of defs) {\n    if (def.name === undefined) {\n      throw new Error(\n        'paramsSnapshot: every definition must have a `name` set. Add `{ name: \"<unique>\" }` to defineParams.',\n      )\n    }\n    if (seenNames.has(def.name)) {\n      throw new Error(\n        `paramsSnapshot: duplicate definition name '${def.name}'. Snapshot keys would collide.`,\n      )\n    }\n    seenNames.add(def.name)\n\n    let values: unknown = undefined\n    try {\n      values = def.storage.read() ?? {}\n    } catch {\n      values = {}\n    }\n    out[def.name] = values\n  }\n\n  return out\n}\n\n/**\n * Client-side: pre-seed the params store cache from a server-rendered\n * snapshot. Must run BEFORE the first `useParams(def)` / `getParamsStore(def)`\n * call to avoid a flicker.\n *\n * For each entry in the snapshot, looks up the definition by name (must have\n * been imported / `defineParams` already evaluated on the client) and seeds\n * the pre-hydration cache. The first `ParamsStore` constructed for that def\n * uses the seeded values instead of calling its storage backend's `read()`.\n *\n * Idempotent — re-calling overwrites. Definitions whose names aren't in the\n * snapshot use their normal storage hydration path.\n */\nexport function hydrateParams(snapshot: ParamsSnapshot): void {\n  for (const [name, values] of Object.entries(snapshot)) {\n    setPreHydrationValues(name, values)\n    // Tolerate names with no matching def — the def may load lazily via a\n    // dynamic import. The pre-hydration cache holds the values until the\n    // matching ParamsStore is constructed.\n    void getDefByName(name)\n  }\n}\n","import type { ParamsDefinition } from './types'\n\n/**\n * Side-effect registry of all definitions that carry a `name`. Populated by\n * `defineParams()` at construction time so `paramsSnapshot()` and\n * `hydrateParams()` can look up defs by name.\n *\n * Last-write-wins: re-defining the same name overwrites silently (the\n * duplicate-name DEV warning is enforced separately at acquire time in\n * `store-cache.ts`).\n */\nconst nameRegistry = new Map<string, ParamsDefinition<unknown>>()\n\n/**\n * Pre-hydration cache for SSR snapshots. `hydrateParams(snapshot)` populates\n * this; `ParamsStore` checks it during initial hydration and uses the seeded\n * values instead of calling the storage backend's `read()`.\n *\n * Once consumed by a store on first hydration the entry is left in place\n * (idempotent re-hydrate) — the consumer can call `hydrateParams()` again\n * with overrides if needed before any store is constructed.\n */\nconst preHydrationCache = new Map<string, unknown>()\n\nexport function registerNamedDef<T>(def: ParamsDefinition<T>): void {\n  if (def.name === undefined) return\n  nameRegistry.set(def.name, def as ParamsDefinition<unknown>)\n}\n\nexport function getDefByName(name: string): ParamsDefinition<unknown> | undefined {\n  return nameRegistry.get(name)\n}\n\nexport function getRegisteredDefs(): ReadonlyArray<ParamsDefinition<unknown>> {\n  return Array.from(nameRegistry.values())\n}\n\nexport function setPreHydrationValues(name: string, values: unknown): void {\n  preHydrationCache.set(name, values)\n}\n\nexport function takePreHydrationValues<T>(name: string | undefined): Partial<T> | undefined {\n  if (name === undefined) return undefined\n  if (!preHydrationCache.has(name)) return undefined\n  return preHydrationCache.get(name) as Partial<T>\n}\n\n/** Test-only: clear both registries. Not exported from the package. */\nexport function _resetNameRegistry(): void {\n  nameRegistry.clear()\n  preHydrationCache.clear()\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACWA,IAAM,eAAe,oBAAI,IAAuC;AAWhE,IAAM,oBAAoB,oBAAI,IAAqB;AAO5C,SAAS,aAAa,MAAqD;AAChF,SAAO,aAAa,IAAI,IAAI;AAC9B;AAMO,SAAS,sBAAsB,MAAc,QAAuB;AACzE,oBAAkB,IAAI,MAAM,MAAM;AACpC;;;ADdO,SAAS,eAAe,MAAmD;AAChF,QAAM,MAAsB,CAAC;AAC7B,QAAM,YAAY,oBAAI,IAAY;AAElC,aAAW,OAAO,MAAM;AACtB,QAAI,IAAI,SAAS,QAAW;AAC1B,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AACA,QAAI,UAAU,IAAI,IAAI,IAAI,GAAG;AAC3B,YAAM,IAAI;AAAA,QACR,8CAA8C,IAAI,IAAI;AAAA,MACxD;AAAA,IACF;AACA,cAAU,IAAI,IAAI,IAAI;AAEtB,QAAI,SAAkB;AACtB,QAAI;AACF,eAAS,IAAI,QAAQ,KAAK,KAAK,CAAC;AAAA,IAClC,QAAQ;AACN,eAAS,CAAC;AAAA,IACZ;AACA,QAAI,IAAI,IAAI,IAAI;AAAA,EAClB;AAEA,SAAO;AACT;AAeO,SAAS,cAAc,UAAgC;AAC5D,aAAW,CAAC,MAAM,MAAM,KAAK,OAAO,QAAQ,QAAQ,GAAG;AACrD,0BAAsB,MAAM,MAAM;AAIlC,SAAK,aAAa,IAAI;AAAA,EACxB;AACF;","names":[]}

package/dist/snapshot.d.cts

@@ -0,0 +1,42 @@
+import { a as ParamsDefinition } from './types-BSWKH-jw.cjs';
+import '@standard-schema/spec';
+import './storage-DBLIRR-4.cjs';
+
+/**
+ * Snapshot keyed by definition name. Returned from `paramsSnapshot()` and
+ * accepted by `hydrateParams()` — round-trip transport for SSR.
+ */
+type ParamsSnapshot = Record<string, unknown>;
+/**
+ * Server-side: produce a snapshot of the current values for the given
+ * definitions, keyed by `def.name`. The returned object is JSON-serializable
+ * (call `JSON.stringify` to embed in HTML, or pass through your framework's
+ * data-loader contract).
+ *
+ * Each definition MUST have a `name` set (added in v0.1 for forward-compat,
+ * load-bearing in v0.2). Throws otherwise.
+ *
+ * Throws on duplicate names — the snapshot keys would collide.
+ *
+ * Reads via the synchronous `def.storage.read()` path. Definitions backed by
+ * an async-only backend (sync `read()` returns undefined) snapshot as
+ * defaults; pair them with a server-side prefetch step before calling
+ * `paramsSnapshot()` if you want their fetched values in the snapshot.
+ */
+declare function paramsSnapshot(defs: readonly ParamsDefinition[]): ParamsSnapshot;
+/**
+ * Client-side: pre-seed the params store cache from a server-rendered
+ * snapshot. Must run BEFORE the first `useParams(def)` / `getParamsStore(def)`
+ * call to avoid a flicker.
+ *
+ * For each entry in the snapshot, looks up the definition by name (must have
+ * been imported / `defineParams` already evaluated on the client) and seeds
+ * the pre-hydration cache. The first `ParamsStore` constructed for that def
+ * uses the seeded values instead of calling its storage backend's `read()`.
+ *
+ * Idempotent — re-calling overwrites. Definitions whose names aren't in the
+ * snapshot use their normal storage hydration path.
+ */
+declare function hydrateParams(snapshot: ParamsSnapshot): void;
+
+export { type ParamsSnapshot, hydrateParams, paramsSnapshot };

package/dist/snapshot.d.ts

@@ -0,0 +1,42 @@
+import { a as ParamsDefinition } from './types-BUmNpSyP.js';
+import '@standard-schema/spec';
+import './storage-DBLIRR-4.js';
+
+/**
+ * Snapshot keyed by definition name. Returned from `paramsSnapshot()` and
+ * accepted by `hydrateParams()` — round-trip transport for SSR.
+ */
+type ParamsSnapshot = Record<string, unknown>;
+/**
+ * Server-side: produce a snapshot of the current values for the given
+ * definitions, keyed by `def.name`. The returned object is JSON-serializable
+ * (call `JSON.stringify` to embed in HTML, or pass through your framework's
+ * data-loader contract).
+ *
+ * Each definition MUST have a `name` set (added in v0.1 for forward-compat,
+ * load-bearing in v0.2). Throws otherwise.
+ *
+ * Throws on duplicate names — the snapshot keys would collide.
+ *
+ * Reads via the synchronous `def.storage.read()` path. Definitions backed by
+ * an async-only backend (sync `read()` returns undefined) snapshot as
+ * defaults; pair them with a server-side prefetch step before calling
+ * `paramsSnapshot()` if you want their fetched values in the snapshot.
+ */
+declare function paramsSnapshot(defs: readonly ParamsDefinition[]): ParamsSnapshot;
+/**
+ * Client-side: pre-seed the params store cache from a server-rendered
+ * snapshot. Must run BEFORE the first `useParams(def)` / `getParamsStore(def)`
+ * call to avoid a flicker.
+ *
+ * For each entry in the snapshot, looks up the definition by name (must have
+ * been imported / `defineParams` already evaluated on the client) and seeds
+ * the pre-hydration cache. The first `ParamsStore` constructed for that def
+ * uses the seeded values instead of calling its storage backend's `read()`.
+ *
+ * Idempotent — re-calling overwrites. Definitions whose names aren't in the
+ * snapshot use their normal storage hydration path.
+ */
+declare function hydrateParams(snapshot: ParamsSnapshot): void;
+
+export { type ParamsSnapshot, hydrateParams, paramsSnapshot };

package/dist/snapshot.js

@@ -0,0 +1,42 @@
+import {
+  getDefByName,
+  setPreHydrationValues
+} from "./chunk-5NSLHAHG.js";
+
+// src/snapshot.ts
+function paramsSnapshot(defs) {
+  const out = {};
+  const seenNames = /* @__PURE__ */ new Set();
+  for (const def of defs) {
+    if (def.name === void 0) {
+      throw new Error(
+        'paramsSnapshot: every definition must have a `name` set. Add `{ name: "<unique>" }` to defineParams.'
+      );
+    }
+    if (seenNames.has(def.name)) {
+      throw new Error(
+        `paramsSnapshot: duplicate definition name '${def.name}'. Snapshot keys would collide.`
+      );
+    }
+    seenNames.add(def.name);
+    let values = void 0;
+    try {
+      values = def.storage.read() ?? {};
+    } catch {
+      values = {};
+    }
+    out[def.name] = values;
+  }
+  return out;
+}
+function hydrateParams(snapshot) {
+  for (const [name, values] of Object.entries(snapshot)) {
+    setPreHydrationValues(name, values);
+    void getDefByName(name);
+  }
+}
+export {
+  hydrateParams,
+  paramsSnapshot
+};
+//# sourceMappingURL=snapshot.js.map

package/dist/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/snapshot.ts"],"sourcesContent":["import { getDefByName, setPreHydrationValues } from './name-registry'\nimport type { ParamsDefinition } from './types'\n\n/**\n * Snapshot keyed by definition name. Returned from `paramsSnapshot()` and\n * accepted by `hydrateParams()` — round-trip transport for SSR.\n */\nexport type ParamsSnapshot = Record<string, unknown>\n\n/**\n * Server-side: produce a snapshot of the current values for the given\n * definitions, keyed by `def.name`. The returned object is JSON-serializable\n * (call `JSON.stringify` to embed in HTML, or pass through your framework's\n * data-loader contract).\n *\n * Each definition MUST have a `name` set (added in v0.1 for forward-compat,\n * load-bearing in v0.2). Throws otherwise.\n *\n * Throws on duplicate names — the snapshot keys would collide.\n *\n * Reads via the synchronous `def.storage.read()` path. Definitions backed by\n * an async-only backend (sync `read()` returns undefined) snapshot as\n * defaults; pair them with a server-side prefetch step before calling\n * `paramsSnapshot()` if you want their fetched values in the snapshot.\n */\nexport function paramsSnapshot(defs: readonly ParamsDefinition[]): ParamsSnapshot {\n  const out: ParamsSnapshot = {}\n  const seenNames = new Set<string>()\n\n  for (const def of defs) {\n    if (def.name === undefined) {\n      throw new Error(\n        'paramsSnapshot: every definition must have a `name` set. Add `{ name: \"<unique>\" }` to defineParams.',\n      )\n    }\n    if (seenNames.has(def.name)) {\n      throw new Error(\n        `paramsSnapshot: duplicate definition name '${def.name}'. Snapshot keys would collide.`,\n      )\n    }\n    seenNames.add(def.name)\n\n    let values: unknown = undefined\n    try {\n      values = def.storage.read() ?? {}\n    } catch {\n      values = {}\n    }\n    out[def.name] = values\n  }\n\n  return out\n}\n\n/**\n * Client-side: pre-seed the params store cache from a server-rendered\n * snapshot. Must run BEFORE the first `useParams(def)` / `getParamsStore(def)`\n * call to avoid a flicker.\n *\n * For each entry in the snapshot, looks up the definition by name (must have\n * been imported / `defineParams` already evaluated on the client) and seeds\n * the pre-hydration cache. The first `ParamsStore` constructed for that def\n * uses the seeded values instead of calling its storage backend's `read()`.\n *\n * Idempotent — re-calling overwrites. Definitions whose names aren't in the\n * snapshot use their normal storage hydration path.\n */\nexport function hydrateParams(snapshot: ParamsSnapshot): void {\n  for (const [name, values] of Object.entries(snapshot)) {\n    setPreHydrationValues(name, values)\n    // Tolerate names with no matching def — the def may load lazily via a\n    // dynamic import. The pre-hydration cache holds the values until the\n    // matching ParamsStore is constructed.\n    void getDefByName(name)\n  }\n}\n"],"mappings":";;;;;;AAyBO,SAAS,eAAe,MAAmD;AAChF,QAAM,MAAsB,CAAC;AAC7B,QAAM,YAAY,oBAAI,IAAY;AAElC,aAAW,OAAO,MAAM;AACtB,QAAI,IAAI,SAAS,QAAW;AAC1B,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AACA,QAAI,UAAU,IAAI,IAAI,IAAI,GAAG;AAC3B,YAAM,IAAI;AAAA,QACR,8CAA8C,IAAI,IAAI;AAAA,MACxD;AAAA,IACF;AACA,cAAU,IAAI,IAAI,IAAI;AAEtB,QAAI,SAAkB;AACtB,QAAI;AACF,eAAS,IAAI,QAAQ,KAAK,KAAK,CAAC;AAAA,IAClC,QAAQ;AACN,eAAS,CAAC;AAAA,IACZ;AACA,QAAI,IAAI,IAAI,IAAI;AAAA,EAClB;AAEA,SAAO;AACT;AAeO,SAAS,cAAc,UAAgC;AAC5D,aAAW,CAAC,MAAM,MAAM,KAAK,OAAO,QAAQ,QAAQ,GAAG;AACrD,0BAAsB,MAAM,MAAM;AAIlC,SAAK,aAAa,IAAI;AAAA,EACxB;AACF;","names":[]}

package/dist/storage/compose.cjs

@@ -0,0 +1,196 @@
+"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/compose/index.ts
+var compose_exports = {};
+__export(compose_exports, {
+  composeStorage: () => composeStorage
+});
+module.exports = __toCommonJS(compose_exports);
+
+// ../utils/src/deep.ts
+function deepEqual(a, b) {
+  if (Object.is(a, b)) return true;
+  if (typeof a !== typeof b) return false;
+  if (a === null || b === null) return false;
+  if (typeof a !== "object") return false;
+  if (Array.isArray(a)) {
+    if (!Array.isArray(b)) return false;
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (!deepEqual(a[i], b[i])) return false;
+    }
+    return true;
+  }
+  if (Array.isArray(b)) return false;
+  if (a instanceof Date) {
+    return b instanceof Date && a.getTime() === b.getTime();
+  }
+  if (b instanceof Date) return false;
+  if (a instanceof RegExp) {
+    return b instanceof RegExp && a.source === b.source && a.flags === b.flags;
+  }
+  if (b instanceof RegExp) return false;
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  if (aKeys.length !== bKeys.length) return false;
+  for (const key of aKeys) {
+    if (!Object.hasOwn(b, key)) return false;
+    if (!deepEqual(a[key], b[key])) {
+      return false;
+    }
+  }
+  return true;
+}
+
+// src/dev.ts
+var isDev = (() => {
+  try {
+    return typeof process !== "undefined" && process?.env?.NODE_ENV !== "production";
+  } catch {
+    return false;
+  }
+})();
+var warned = /* @__PURE__ */ new Set();
+function warn(message) {
+  if (!isDev) return;
+  if (warned.has(message)) return;
+  warned.add(message);
+  console.warn(`[@victorylabs/params] ${message}`);
+}
+
+// src/storage/compose/index.ts
+function composeStorage(backends, opts = {}) {
+  if (backends.length === 0) {
+    throw new Error("composeStorage: requires at least one backend");
+  }
+  const readStrategy = opts.readStrategy ?? "first";
+  const writeStrategy = opts.writeStrategy ?? "all";
+  const name = opts.name ?? `composeStorage(${backends.map((b) => b.name).join("+")})`;
+  return {
+    name,
+    // composeStorage runs on the server only if EVERY backend allows it.
+    // Otherwise the server skips the read and the engine uses defaults.
+    clientOnly: backends.every((b) => b.clientOnly === true),
+    read: () => {
+      if (readStrategy === "first") {
+        for (const b of backends) {
+          const v = b.read();
+          if (v !== void 0) return v;
+        }
+        return void 0;
+      }
+      let merged;
+      for (const b of backends) {
+        const v = b.read();
+        if (v === void 0) continue;
+        merged = deepMergeObjects(merged, v);
+      }
+      return merged;
+    },
+    readAsync: async () => {
+      if (readStrategy === "first") {
+        for (const b of backends) {
+          const v = b.readAsync ? await b.readAsync() : b.read();
+          if (v !== void 0) return v;
+        }
+        return void 0;
+      }
+      let merged;
+      for (const b of backends) {
+        const v = b.readAsync ? await b.readAsync() : b.read();
+        if (v === void 0) continue;
+        merged = deepMergeObjects(merged, v);
+      }
+      return merged;
+    },
+    write: async (values, changed, options) => {
+      if (writeStrategy === "first") {
+        try {
+          await backends[0]?.write(values, changed, options);
+        } catch {
+        }
+        return;
+      }
+      const promises = [];
+      for (const b of backends) {
+        try {
+          const result = b.write(values, changed, options);
+          if (result && typeof result.then === "function") {
+            promises.push(
+              result.catch((err) => {
+                warn(
+                  `composeStorage: backend '${b.name}' write failed: ${err instanceof Error ? err.message : String(err)}`
+                );
+              })
+            );
+          }
+        } catch (err) {
+          warn(
+            `composeStorage: backend '${b.name}' write threw synchronously: ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
+      }
+      await Promise.all(promises);
+    },
+    subscribe: (callback) => {
+      let lastEmit;
+      const unsubscribers = [];
+      for (const b of backends) {
+        if (!b.subscribe) continue;
+        const unsub = b.subscribe((values) => {
+          if (lastEmit !== void 0 && deepEqual(lastEmit, values)) return;
+          lastEmit = values;
+          callback(values);
+        });
+        unsubscribers.push(unsub);
+      }
+      return () => {
+        for (const unsub of unsubscribers) unsub();
+      };
+    },
+    clear: async (paths, options) => {
+      for (const b of backends) {
+        if (!b.clear) continue;
+        try {
+          const result = b.clear(paths, options);
+          if (result && typeof result.then === "function") {
+            await result;
+          }
+        } catch {
+        }
+      }
+    }
+  };
+}
+function deepMergeObjects(a, b) {
+  if (a === void 0) return b;
+  if (a === null || typeof a !== "object" || Array.isArray(a)) return b;
+  if (b === null || typeof b !== "object" || Array.isArray(b)) return b;
+  const out = { ...a };
+  for (const [key, value] of Object.entries(b)) {
+    out[key] = deepMergeObjects(out[key], value);
+  }
+  return out;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  composeStorage
+});
+//# sourceMappingURL=compose.cjs.map

package/dist/storage/compose.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/storage/compose/index.ts","../../../utils/src/deep.ts","../../src/dev.ts"],"sourcesContent":["import { deepEqual } from '@victorylabs/utils'\n\nimport { warn } from '../../dev'\nimport type { ParamsStorage } from '../../storage'\n\nexport interface ComposeStorageOptions {\n  /**\n   * Read strategy.\n   * - `'first'` (default): walks the backends, returns the first non-undefined.\n   * - `'merge'`: deep-merges all backends; later entries win on conflict. Arrays\n   *   are **replaced** (later wins), not concatenated — concatenation would\n   *   produce duplicates on every read.\n   */\n  readStrategy?: 'first' | 'merge'\n\n  /**\n   * Write strategy.\n   * - `'all'` (default): fan out the write to every backend. Per-backend\n   *   failures are swallowed with a dev warning; one bad backend doesn't\n   *   block the others.\n   * - `'first'`: writes only to the first backend. Subsequent backends are\n   *   read-only mirrors.\n   */\n  writeStrategy?: 'all' | 'first'\n\n  /** Diagnostics name. Default: `'composeStorage(name1+name2+...)'`. */\n  name?: string\n}\n\n/**\n * Layer multiple storage backends. Common case: URL primary + localStorage\n * fallback (URL works for shareable links; localStorage survives navigation\n * away from the URL-bearing page). Or: cookieStorage primary + serverStorage\n * mirror (fast local read; eventually-consistent server sync).\n *\n * Composing backends through `composeStorage` itself is allowed — recursive\n * layering nests cleanly.\n */\nexport function composeStorage<T>(\n  backends: ReadonlyArray<ParamsStorage<T>>,\n  opts: ComposeStorageOptions = {},\n): ParamsStorage<T> {\n  if (backends.length === 0) {\n    throw new Error('composeStorage: requires at least one backend')\n  }\n\n  const readStrategy = opts.readStrategy ?? 'first'\n  const writeStrategy = opts.writeStrategy ?? 'all'\n  const name = opts.name ?? `composeStorage(${backends.map((b) => b.name).join('+')})`\n\n  return {\n    name,\n    // composeStorage runs on the server only if EVERY backend allows it.\n    // Otherwise the server skips the read and the engine uses defaults.\n    clientOnly: backends.every((b) => b.clientOnly === true),\n\n    read: () => {\n      if (readStrategy === 'first') {\n        for (const b of backends) {\n          const v = b.read()\n          if (v !== undefined) return v\n        }\n        return undefined\n      }\n      // 'merge'\n      let merged: Partial<T> | undefined\n      for (const b of backends) {\n        const v = b.read()\n        if (v === undefined) continue\n        merged = deepMergeObjects(merged, v) as Partial<T>\n      }\n      return merged\n    },\n\n    readAsync: async () => {\n      if (readStrategy === 'first') {\n        for (const b of backends) {\n          const v = b.readAsync ? await b.readAsync() : b.read()\n          if (v !== undefined) return v\n        }\n        return undefined\n      }\n      // 'merge'\n      let merged: Partial<T> | undefined\n      for (const b of backends) {\n        const v = b.readAsync ? await b.readAsync() : b.read()\n        if (v === undefined) continue\n        merged = deepMergeObjects(merged, v) as Partial<T>\n      }\n      return merged\n    },\n\n    write: async (values, changed, options) => {\n      if (writeStrategy === 'first') {\n        try {\n          await backends[0]?.write(values, changed, options)\n        } catch {\n          // Silent fallback per the storage error contract.\n        }\n        return\n      }\n      // 'all' — fan out, swallow individual failures with dev warning.\n      const promises: Array<Promise<void>> = []\n      for (const b of backends) {\n        try {\n          const result = b.write(values, changed, options)\n          if (result && typeof (result as Promise<void>).then === 'function') {\n            promises.push(\n              (result as Promise<void>).catch((err: unknown) => {\n                warn(\n                  `composeStorage: backend '${b.name}' write failed: ${err instanceof Error ? err.message : String(err)}`,\n                )\n              }),\n            )\n          }\n        } catch (err) {\n          warn(\n            `composeStorage: backend '${b.name}' write threw synchronously: ${err instanceof Error ? err.message : String(err)}`,\n          )\n        }\n      }\n      await Promise.all(promises)\n    },\n\n    subscribe: (callback) => {\n      let lastEmit: Partial<T> | undefined\n      const unsubscribers: Array<() => void> = []\n      for (const b of backends) {\n        if (!b.subscribe) continue\n        const unsub = b.subscribe((values) => {\n          // Cross-backend de-dup: drop back-to-back identical emits.\n          if (lastEmit !== undefined && deepEqual(lastEmit, values)) return\n          lastEmit = values\n          callback(values)\n        })\n        unsubscribers.push(unsub)\n      }\n      return () => {\n        for (const unsub of unsubscribers) unsub()\n      }\n    },\n\n    clear: async (paths, options) => {\n      for (const b of backends) {\n        if (!b.clear) continue\n        try {\n          const result = b.clear(paths, options)\n          if (result && typeof (result as Promise<void>).then === 'function') {\n            await (result as Promise<void>)\n          }\n        } catch {\n          // Silent fallback.\n        }\n      }\n    },\n  }\n}\n\n/**\n * Deep-merge two values with later-wins semantics. Arrays are REPLACED, not\n * concatenated — concatenation would produce duplicates on every read.\n * Plain objects merge recursively. Primitives are replaced.\n */\nfunction deepMergeObjects(a: unknown, b: unknown): unknown {\n  if (a === undefined) return b\n  if (a === null || typeof a !== 'object' || Array.isArray(a)) return b\n  if (b === null || typeof b !== 'object' || Array.isArray(b)) return b\n  const out: Record<string, unknown> = { ...(a as Record<string, unknown>) }\n  for (const [key, value] of Object.entries(b as Record<string, unknown>)) {\n    out[key] = deepMergeObjects(out[key], value)\n  }\n  return out\n}\n","/**\n * Path-aware deep helpers. Paths are dot-strings: 'address.street', 'tags.2'.\n * Numeric segments index into arrays; string segments index into objects.\n *\n * Limitation: keys containing literal '.' are not supported. Document this\n * for consumers; forms with such keys are vanishingly rare.\n */\n\nexport function splitPath(path: string): string[] {\n  if (path === '') return []\n  return path.split('.')\n}\n\nexport function deepGet(obj: unknown, path: string): unknown {\n  const segments = splitPath(path)\n  let current: unknown = obj\n  for (const seg of segments) {\n    if (current === null || current === undefined) return undefined\n    if (Array.isArray(current)) {\n      const idx = Number(seg)\n      if (!Number.isInteger(idx) || idx < 0) return undefined\n      current = current[idx]\n    } else if (typeof current === 'object') {\n      current = (current as Record<string, unknown>)[seg]\n    } else {\n      return undefined\n    }\n  }\n  return current\n}\n\nexport function deepSet<T>(obj: T, path: string, value: unknown): T {\n  const segments = splitPath(path)\n  if (segments.length === 0) return value as T\n  return setRecursive(obj, segments, 0, value) as T\n}\n\nfunction setRecursive(current: unknown, segments: string[], i: number, value: unknown): unknown {\n  const seg = segments[i]\n  // Sanity: segments.length > i always when this runs (caller ensures).\n  if (seg === undefined) return value\n  const isLast = i === segments.length - 1\n  const idx = Number(seg)\n  const isNumericSeg = Number.isInteger(idx) && idx >= 0 && /^\\d+$/.test(seg)\n\n  if (isNumericSeg) {\n    const arr = Array.isArray(current) ? current.slice() : []\n    arr[idx] = isLast ? value : setRecursive(arr[idx], segments, i + 1, value)\n    return arr\n  }\n\n  const next: Record<string, unknown> =\n    current && typeof current === 'object' && !Array.isArray(current)\n      ? { ...(current as Record<string, unknown>) }\n      : {}\n  next[seg] = isLast ? value : setRecursive(next[seg], segments, i + 1, value)\n  return next\n}\n\nexport function deepEqual(a: unknown, b: unknown): boolean {\n  if (Object.is(a, b)) return true\n  if (typeof a !== typeof b) return false\n  if (a === null || b === null) return false\n  if (typeof a !== 'object') return false\n\n  if (Array.isArray(a)) {\n    if (!Array.isArray(b)) return false\n    if (a.length !== b.length) return false\n    for (let i = 0; i < a.length; i++) {\n      if (!deepEqual(a[i], b[i])) return false\n    }\n    return true\n  }\n  if (Array.isArray(b)) return false\n\n  if (a instanceof Date) {\n    return b instanceof Date && a.getTime() === b.getTime()\n  }\n  if (b instanceof Date) return false\n\n  if (a instanceof RegExp) {\n    return b instanceof RegExp && a.source === b.source && a.flags === b.flags\n  }\n  if (b instanceof RegExp) return false\n\n  const aKeys = Object.keys(a as Record<string, unknown>)\n  const bKeys = Object.keys(b as Record<string, unknown>)\n  if (aKeys.length !== bKeys.length) return false\n  for (const key of aKeys) {\n    if (!Object.hasOwn(b as object, key)) return false\n    if (!deepEqual((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key])) {\n      return false\n    }\n  }\n  return true\n}\n\n/**\n * Deep merge: later sources overwrite earlier ones at scalar/array level;\n * objects merge recursively. Arrays are replaced wholesale (no concatenation),\n * which matches the form-state mental model — an array IS the value.\n */\nexport function deepMerge<T extends object>(...sources: Array<Partial<T> | undefined>): T {\n  const result = {} as Record<string, unknown>\n  for (const source of sources) {\n    if (!source) continue\n    for (const [key, value] of Object.entries(source)) {\n      const existing = result[key]\n      if (\n        existing &&\n        value &&\n        typeof existing === 'object' &&\n        typeof value === 'object' &&\n        !Array.isArray(existing) &&\n        !Array.isArray(value) &&\n        !(existing instanceof Date) &&\n        !(value instanceof Date)\n      ) {\n        result[key] = deepMerge(existing as Partial<object>, value as Partial<object>)\n      } else {\n        result[key] = value\n      }\n    }\n  }\n  return result as T\n}\n","// Bundlers (tsup, vite, webpack) replace `process.env.NODE_ENV` at build time.\n// We declare `process` minimally so TypeScript doesn't require @types/node.\n\ndeclare const process:\n  | {\n      env?: {\n        NODE_ENV?: string\n      }\n    }\n  | undefined\n\nconst isDev = ((): boolean => {\n  try {\n    return typeof process !== 'undefined' && process?.env?.NODE_ENV !== 'production'\n  } catch {\n    return false\n  }\n})()\n\nconst warned = new Set<string>()\n\n/**\n * Emit a one-time dev-mode console warning. Identical messages are\n * suppressed after the first occurrence to avoid log spam.\n */\nexport function warn(message: string): void {\n  if (!isDev) return\n  if (warned.has(message)) return\n  warned.add(message)\n  console.warn(`[@victorylabs/params] ${message}`)\n}\n"],"mappings":"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","names":[]}

package/dist/storage/compose.d.cts

@@ -0,0 +1,35 @@
+import { P as ParamsStorage } from '../storage-DBLIRR-4.cjs';
+
+interface ComposeStorageOptions {
+    /**
+     * Read strategy.
+     * - `'first'` (default): walks the backends, returns the first non-undefined.
+     * - `'merge'`: deep-merges all backends; later entries win on conflict. Arrays
+     *   are **replaced** (later wins), not concatenated — concatenation would
+     *   produce duplicates on every read.
+     */
+    readStrategy?: 'first' | 'merge';
+    /**
+     * Write strategy.
+     * - `'all'` (default): fan out the write to every backend. Per-backend
+     *   failures are swallowed with a dev warning; one bad backend doesn't
+     *   block the others.
+     * - `'first'`: writes only to the first backend. Subsequent backends are
+     *   read-only mirrors.
+     */
+    writeStrategy?: 'all' | 'first';
+    /** Diagnostics name. Default: `'composeStorage(name1+name2+...)'`. */
+    name?: string;
+}
+/**
+ * Layer multiple storage backends. Common case: URL primary + localStorage
+ * fallback (URL works for shareable links; localStorage survives navigation
+ * away from the URL-bearing page). Or: cookieStorage primary + serverStorage
+ * mirror (fast local read; eventually-consistent server sync).
+ *
+ * Composing backends through `composeStorage` itself is allowed — recursive
+ * layering nests cleanly.
+ */
+declare function composeStorage<T>(backends: ReadonlyArray<ParamsStorage<T>>, opts?: ComposeStorageOptions): ParamsStorage<T>;
+
+export { type ComposeStorageOptions, composeStorage };

package/dist/storage/compose.d.ts

@@ -0,0 +1,35 @@
+import { P as ParamsStorage } from '../storage-DBLIRR-4.js';
+
+interface ComposeStorageOptions {
+    /**
+     * Read strategy.
+     * - `'first'` (default): walks the backends, returns the first non-undefined.
+     * - `'merge'`: deep-merges all backends; later entries win on conflict. Arrays
+     *   are **replaced** (later wins), not concatenated — concatenation would
+     *   produce duplicates on every read.
+     */
+    readStrategy?: 'first' | 'merge';
+    /**
+     * Write strategy.
+     * - `'all'` (default): fan out the write to every backend. Per-backend
+     *   failures are swallowed with a dev warning; one bad backend doesn't
+     *   block the others.
+     * - `'first'`: writes only to the first backend. Subsequent backends are
+     *   read-only mirrors.
+     */
+    writeStrategy?: 'all' | 'first';
+    /** Diagnostics name. Default: `'composeStorage(name1+name2+...)'`. */
+    name?: string;
+}
+/**
+ * Layer multiple storage backends. Common case: URL primary + localStorage
+ * fallback (URL works for shareable links; localStorage survives navigation
+ * away from the URL-bearing page). Or: cookieStorage primary + serverStorage
+ * mirror (fast local read; eventually-consistent server sync).
+ *
+ * Composing backends through `composeStorage` itself is allowed — recursive
+ * layering nests cleanly.
+ */
+declare function composeStorage<T>(backends: ReadonlyArray<ParamsStorage<T>>, opts?: ComposeStorageOptions): ParamsStorage<T>;
+
+export { type ComposeStorageOptions, composeStorage };

package/dist/storage/compose.js

@@ -0,0 +1,123 @@
+import {
+  deepEqual,
+  warn
+} from "../chunk-4T4THPFW.js";
+
+// src/storage/compose/index.ts
+function composeStorage(backends, opts = {}) {
+  if (backends.length === 0) {
+    throw new Error("composeStorage: requires at least one backend");
+  }
+  const readStrategy = opts.readStrategy ?? "first";
+  const writeStrategy = opts.writeStrategy ?? "all";
+  const name = opts.name ?? `composeStorage(${backends.map((b) => b.name).join("+")})`;
+  return {
+    name,
+    // composeStorage runs on the server only if EVERY backend allows it.
+    // Otherwise the server skips the read and the engine uses defaults.
+    clientOnly: backends.every((b) => b.clientOnly === true),
+    read: () => {
+      if (readStrategy === "first") {
+        for (const b of backends) {
+          const v = b.read();
+          if (v !== void 0) return v;
+        }
+        return void 0;
+      }
+      let merged;
+      for (const b of backends) {
+        const v = b.read();
+        if (v === void 0) continue;
+        merged = deepMergeObjects(merged, v);
+      }
+      return merged;
+    },
+    readAsync: async () => {
+      if (readStrategy === "first") {
+        for (const b of backends) {
+          const v = b.readAsync ? await b.readAsync() : b.read();
+          if (v !== void 0) return v;
+        }
+        return void 0;
+      }
+      let merged;
+      for (const b of backends) {
+        const v = b.readAsync ? await b.readAsync() : b.read();
+        if (v === void 0) continue;
+        merged = deepMergeObjects(merged, v);
+      }
+      return merged;
+    },
+    write: async (values, changed, options) => {
+      if (writeStrategy === "first") {
+        try {
+          await backends[0]?.write(values, changed, options);
+        } catch {
+        }
+        return;
+      }
+      const promises = [];
+      for (const b of backends) {
+        try {
+          const result = b.write(values, changed, options);
+          if (result && typeof result.then === "function") {
+            promises.push(
+              result.catch((err) => {
+                warn(
+                  `composeStorage: backend '${b.name}' write failed: ${err instanceof Error ? err.message : String(err)}`
+                );
+              })
+            );
+          }
+        } catch (err) {
+          warn(
+            `composeStorage: backend '${b.name}' write threw synchronously: ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
+      }
+      await Promise.all(promises);
+    },
+    subscribe: (callback) => {
+      let lastEmit;
+      const unsubscribers = [];
+      for (const b of backends) {
+        if (!b.subscribe) continue;
+        const unsub = b.subscribe((values) => {
+          if (lastEmit !== void 0 && deepEqual(lastEmit, values)) return;
+          lastEmit = values;
+          callback(values);
+        });
+        unsubscribers.push(unsub);
+      }
+      return () => {
+        for (const unsub of unsubscribers) unsub();
+      };
+    },
+    clear: async (paths, options) => {
+      for (const b of backends) {
+        if (!b.clear) continue;
+        try {
+          const result = b.clear(paths, options);
+          if (result && typeof result.then === "function") {
+            await result;
+          }
+        } catch {
+        }
+      }
+    }
+  };
+}
+function deepMergeObjects(a, b) {
+  if (a === void 0) return b;
+  if (a === null || typeof a !== "object" || Array.isArray(a)) return b;
+  if (b === null || typeof b !== "object" || Array.isArray(b)) return b;
+  const out = { ...a };
+  for (const [key, value] of Object.entries(b)) {
+    out[key] = deepMergeObjects(out[key], value);
+  }
+  return out;
+}
+export {
+  composeStorage
+};
+//# sourceMappingURL=compose.js.map

package/dist/storage/compose.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/storage/compose/index.ts"],"sourcesContent":["import { deepEqual } from '@victorylabs/utils'\n\nimport { warn } from '../../dev'\nimport type { ParamsStorage } from '../../storage'\n\nexport interface ComposeStorageOptions {\n  /**\n   * Read strategy.\n   * - `'first'` (default): walks the backends, returns the first non-undefined.\n   * - `'merge'`: deep-merges all backends; later entries win on conflict. Arrays\n   *   are **replaced** (later wins), not concatenated — concatenation would\n   *   produce duplicates on every read.\n   */\n  readStrategy?: 'first' | 'merge'\n\n  /**\n   * Write strategy.\n   * - `'all'` (default): fan out the write to every backend. Per-backend\n   *   failures are swallowed with a dev warning; one bad backend doesn't\n   *   block the others.\n   * - `'first'`: writes only to the first backend. Subsequent backends are\n   *   read-only mirrors.\n   */\n  writeStrategy?: 'all' | 'first'\n\n  /** Diagnostics name. Default: `'composeStorage(name1+name2+...)'`. */\n  name?: string\n}\n\n/**\n * Layer multiple storage backends. Common case: URL primary + localStorage\n * fallback (URL works for shareable links; localStorage survives navigation\n * away from the URL-bearing page). Or: cookieStorage primary + serverStorage\n * mirror (fast local read; eventually-consistent server sync).\n *\n * Composing backends through `composeStorage` itself is allowed — recursive\n * layering nests cleanly.\n */\nexport function composeStorage<T>(\n  backends: ReadonlyArray<ParamsStorage<T>>,\n  opts: ComposeStorageOptions = {},\n): ParamsStorage<T> {\n  if (backends.length === 0) {\n    throw new Error('composeStorage: requires at least one backend')\n  }\n\n  const readStrategy = opts.readStrategy ?? 'first'\n  const writeStrategy = opts.writeStrategy ?? 'all'\n  const name = opts.name ?? `composeStorage(${backends.map((b) => b.name).join('+')})`\n\n  return {\n    name,\n    // composeStorage runs on the server only if EVERY backend allows it.\n    // Otherwise the server skips the read and the engine uses defaults.\n    clientOnly: backends.every((b) => b.clientOnly === true),\n\n    read: () => {\n      if (readStrategy === 'first') {\n        for (const b of backends) {\n          const v = b.read()\n          if (v !== undefined) return v\n        }\n        return undefined\n      }\n      // 'merge'\n      let merged: Partial<T> | undefined\n      for (const b of backends) {\n        const v = b.read()\n        if (v === undefined) continue\n        merged = deepMergeObjects(merged, v) as Partial<T>\n      }\n      return merged\n    },\n\n    readAsync: async () => {\n      if (readStrategy === 'first') {\n        for (const b of backends) {\n          const v = b.readAsync ? await b.readAsync() : b.read()\n          if (v !== undefined) return v\n        }\n        return undefined\n      }\n      // 'merge'\n      let merged: Partial<T> | undefined\n      for (const b of backends) {\n        const v = b.readAsync ? await b.readAsync() : b.read()\n        if (v === undefined) continue\n        merged = deepMergeObjects(merged, v) as Partial<T>\n      }\n      return merged\n    },\n\n    write: async (values, changed, options) => {\n      if (writeStrategy === 'first') {\n        try {\n          await backends[0]?.write(values, changed, options)\n        } catch {\n          // Silent fallback per the storage error contract.\n        }\n        return\n      }\n      // 'all' — fan out, swallow individual failures with dev warning.\n      const promises: Array<Promise<void>> = []\n      for (const b of backends) {\n        try {\n          const result = b.write(values, changed, options)\n          if (result && typeof (result as Promise<void>).then === 'function') {\n            promises.push(\n              (result as Promise<void>).catch((err: unknown) => {\n                warn(\n                  `composeStorage: backend '${b.name}' write failed: ${err instanceof Error ? err.message : String(err)}`,\n                )\n              }),\n            )\n          }\n        } catch (err) {\n          warn(\n            `composeStorage: backend '${b.name}' write threw synchronously: ${err instanceof Error ? err.message : String(err)}`,\n          )\n        }\n      }\n      await Promise.all(promises)\n    },\n\n    subscribe: (callback) => {\n      let lastEmit: Partial<T> | undefined\n      const unsubscribers: Array<() => void> = []\n      for (const b of backends) {\n        if (!b.subscribe) continue\n        const unsub = b.subscribe((values) => {\n          // Cross-backend de-dup: drop back-to-back identical emits.\n          if (lastEmit !== undefined && deepEqual(lastEmit, values)) return\n          lastEmit = values\n          callback(values)\n        })\n        unsubscribers.push(unsub)\n      }\n      return () => {\n        for (const unsub of unsubscribers) unsub()\n      }\n    },\n\n    clear: async (paths, options) => {\n      for (const b of backends) {\n        if (!b.clear) continue\n        try {\n          const result = b.clear(paths, options)\n          if (result && typeof (result as Promise<void>).then === 'function') {\n            await (result as Promise<void>)\n          }\n        } catch {\n          // Silent fallback.\n        }\n      }\n    },\n  }\n}\n\n/**\n * Deep-merge two values with later-wins semantics. Arrays are REPLACED, not\n * concatenated — concatenation would produce duplicates on every read.\n * Plain objects merge recursively. Primitives are replaced.\n */\nfunction deepMergeObjects(a: unknown, b: unknown): unknown {\n  if (a === undefined) return b\n  if (a === null || typeof a !== 'object' || Array.isArray(a)) return b\n  if (b === null || typeof b !== 'object' || Array.isArray(b)) return b\n  const out: Record<string, unknown> = { ...(a as Record<string, unknown>) }\n  for (const [key, value] of Object.entries(b as Record<string, unknown>)) {\n    out[key] = deepMergeObjects(out[key], value)\n  }\n  return out\n}\n"],"mappings":"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","names":[]}