@victorylabs/params 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Victory Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# @victorylabs/params
+
+Centralized view-state config (filters, sort, pagination, app config) with pluggable storage. Memory by default; URL/localStorage/sessionStorage opt-in. Single React hook DX, schema-validated reads, cross-component sharing.
+
+A focused alternative to `nuqs` / hand-rolled `useSearchParams + useEffect` chains, with:
+
+- **Single hook** — `useParams(def)` returns a controller; everything else flows from `p.`.
+- **Pluggable storage** — memory (default), URL, localStorage, sessionStorage, or your own backend implementing `ParamsStorage<T>`.
+- **Schema-validated reads** — Zod / Standard Schema / plain spec; corrupted external data silently falls back to defaults.
+- **Cross-component sharing** — multiple `useParams(def)` calls in different components share the same store automatically (definition identity).
+- **Per-field debounce + input shadow** — typing feels instant; URL writes are throttled.
+- **Compile-time path safety** — `p.value('emial')` is a TypeScript error.
+- **Deterministic `p.toQuery()`** — alphabetical, suitable for React Query cache keys.
+- **Forms bridge** — `paramsToFormSync(def)` lets `@victorylabs/forms` borrow a params definition (one source of truth for filters + a save-view form).
+
+## Install
+
+```bash
+pnpm add @victorylabs/params zod
+```
+
+`react`, `zod`, and `@victorylabs/forms` are optional peer dependencies. Install only what you use.
+
+## Quick start
+
+```tsx
+import { defineParams } from '@victorylabs/params'
+import { useParams } from '@victorylabs/params/react'
+import { urlStorage } from '@victorylabs/params/storage/url'
+import { z } from 'zod'
+
+const filters = defineParams(
+  {
+    query: z.string().default(''),
+    page:  z.coerce.number().int().min(1).default(1),
+    sort:  z.enum(['asc', 'desc']).default('asc'),
+  },
+  {
+    storage: urlStorage(),
+    fields: {
+      query: { debounce: 300 },
+      page:  { omitWhenDefault: true },
+    },
+  },
+)
+
+export function ProductsPage() {
+  const p = useParams(filters)
+
+  return (
+    <>
+      <input {...p.input('query')} placeholder="Search…" />
+      <select value={p.values.sort} onChange={(e) => p.set('sort', e.target.value as 'asc' | 'desc')}>
+        <option value="asc">A → Z</option>
+        <option value="desc">Z → A</option>
+      </select>
+      <ResultList query={p.deferred('query')} sort={p.value('sort')} page={p.value('page')} />
+      <a href={p.href({ page: p.values.page + 1 })}>Next</a>
+    </>
+  )
+}
+```
+
+## Documentation
+
+Full reference at [the docs site](https://victorylabs.dev/libs/params).
+
+## License
+
+MIT

package/dist/chunk-43PUAYQP.js

@@ -0,0 +1,573 @@
+import {
+  deepEqual,
+  deepGet,
+  deepSet,
+  splitPath,
+  warn
+} from "./chunk-4T4THPFW.js";
+import {
+  takePreHydrationValues
+} from "./chunk-5NSLHAHG.js";
+import {
+  defaultSerialize,
+  extractEnumValues,
+  getDefault,
+  isPlainSpec,
+  isStandardSchema,
+  parseField
+} from "./chunk-NUO3GOXV.js";
+
+// ../utils/src/cascade.ts
+var DEPTH_CAP = 10;
+function resolveCascade(initialChanges, ctx) {
+  const changes = { ...initialChanges };
+  const warnings = [];
+  const working = { ...ctx.currentValues, ...initialChanges };
+  let frontier = new Set(Object.keys(initialChanges));
+  const visited = new Set(frontier);
+  let depth = 0;
+  while (frontier.size > 0) {
+    if (depth >= DEPTH_CAP) {
+      warnings.push(
+        `cascade depth cap (${DEPTH_CAP}) reached; stopping. Frontier: [${[...frontier].join(", ")}]. Likely a config error \u2014 check for accidental long chains.`
+      );
+      break;
+    }
+    const nextFrontier = /* @__PURE__ */ new Set();
+    for (const targetPath of ctx.allPaths) {
+      const config = ctx.fieldConfigs[targetPath];
+      if (!config?.onDepChange) continue;
+      if (frontier.has(targetPath)) continue;
+      const deps = resolveDeps(config, ctx.allPaths, targetPath);
+      const changedDeps = deps.filter((d) => frontier.has(d));
+      if (changedDeps.length === 0) continue;
+      if (visited.has(targetPath)) {
+        warnings.push(
+          `cycle detected: '${targetPath}' would cascade twice (triggered by [${changedDeps.join(", ")}]). Skipping re-entry.`
+        );
+        continue;
+      }
+      const newValue = applyDepChange(config.onDepChange, deps, working, ctx.defaults, targetPath);
+      if (Object.is(newValue, working[targetPath])) continue;
+      changes[targetPath] = newValue;
+      working[targetPath] = newValue;
+      visited.add(targetPath);
+      nextFrontier.add(targetPath);
+    }
+    frontier = nextFrontier;
+    depth++;
+  }
+  return { changes, warnings };
+}
+function resolveDeps(config, allPaths, selfPath) {
+  if (config.dependsOn === "*") {
+    const exclude = new Set(config.excludeDeps ?? []);
+    exclude.add(selfPath);
+    return allPaths.filter((p) => !exclude.has(p));
+  }
+  if (Array.isArray(config.dependsOn)) {
+    return config.dependsOn.filter((p) => p !== selfPath);
+  }
+  return [];
+}
+function applyDepChange(onDepChange, deps, working, defaults, targetPath) {
+  if (onDepChange === "reset") return defaults[targetPath];
+  if (onDepChange === "clear") return void 0;
+  const depsRecord = {};
+  for (const d of deps) {
+    depsRecord[d] = working[d];
+  }
+  return onDepChange(depsRecord, working[targetPath]);
+}
+
+// ../utils/src/path-trie.ts
+var makeNode = () => ({ listeners: /* @__PURE__ */ new Set(), children: /* @__PURE__ */ new Map() });
+var PathTrie = class {
+  root = makeNode();
+  subscribe(path, listener) {
+    const node = this.ensure(path);
+    node.listeners.add(listener);
+    return () => {
+      node.listeners.delete(listener);
+    };
+  }
+  notify(path) {
+    const segments = splitPath(path);
+    let current = this.root;
+    fire(current);
+    for (const seg of segments) {
+      const next = current.children.get(seg);
+      if (!next) return;
+      current = next;
+      fire(current);
+    }
+    fireSubtree(current);
+  }
+  /** Test/diagnostic helper — total subscriber count below a given path. */
+  size(path = "") {
+    const node = this.find(path);
+    if (!node) return 0;
+    return countSubtree(node);
+  }
+  ensure(path) {
+    let node = this.root;
+    for (const seg of splitPath(path)) {
+      let child = node.children.get(seg);
+      if (!child) {
+        child = makeNode();
+        node.children.set(seg, child);
+      }
+      node = child;
+    }
+    return node;
+  }
+  find(path) {
+    let node = this.root;
+    for (const seg of splitPath(path)) {
+      node = node?.children.get(seg);
+      if (!node) return void 0;
+    }
+    return node;
+  }
+};
+function fire(node) {
+  for (const listener of node.listeners) listener();
+}
+function fireSubtree(node) {
+  for (const child of node.children.values()) {
+    fire(child);
+    fireSubtree(child);
+  }
+}
+function countSubtree(node) {
+  let total = node.listeners.size;
+  for (const child of node.children.values()) {
+    total += countSubtree(child);
+  }
+  return total;
+}
+
+// src/params-store.ts
+var isClient = typeof window !== "undefined";
+var ParamsStore = class {
+  spec;
+  storage;
+  fieldConfigs;
+  values;
+  defaults;
+  trie = new PathTrie();
+  storageErrorMap = /* @__PURE__ */ new Map();
+  lastWritten;
+  storageUnsubscribe;
+  toQueryCache;
+  disposed = false;
+  constructor(def) {
+    this.spec = def.spec;
+    this.storage = def.storage;
+    this.fieldConfigs = def.fields;
+    this.defaults = this.computeDefaults();
+    this.values = { ...this.defaults };
+    const seeded = takePreHydrationValues(def.name);
+    if (seeded !== void 0) {
+      this.values = { ...this.defaults, ...seeded };
+    } else if (this.storage.clientOnly && !isClient) {
+    } else {
+      this.hydrateFromStorage();
+    }
+    if (this.storage.subscribe) {
+      this.storageUnsubscribe = this.storage.subscribe((raw) => this.onExternalChange(raw));
+    }
+  }
+  // ─── Reads (synchronous, framework-agnostic) ──────────────────────────
+  getValues() {
+    return this.values;
+  }
+  getValue(path) {
+    return deepGet(this.values, path);
+  }
+  /** Storage parse failures discovered on hydrate or external change. */
+  get storageErrors() {
+    const out = {};
+    for (const [path, reason] of this.storageErrorMap) out[path] = reason;
+    return out;
+  }
+  /** Per-field config (for the React adapter to read debounce settings, etc.). */
+  getFieldConfig(path) {
+    return this.fieldConfigs[path];
+  }
+  set(pathOrPartial, valueOrOptions, maybeOptions) {
+    if (this.disposed) return;
+    let updates;
+    let options;
+    if (typeof pathOrPartial === "string") {
+      updates = { [pathOrPartial]: valueOrOptions };
+      options = maybeOptions;
+    } else {
+      updates = pathOrPartial;
+      options = valueOrOptions;
+    }
+    const initialChanges = {};
+    for (const [path, v] of Object.entries(updates)) {
+      const old = deepGet(this.values, path);
+      if (deepEqual(old, v)) continue;
+      initialChanges[path] = v;
+    }
+    if (Object.keys(initialChanges).length === 0) return;
+    const cascade = resolveCascade(initialChanges, {
+      fieldConfigs: this.fieldConfigs,
+      defaults: this.defaults,
+      currentValues: this.values,
+      allPaths: Object.keys(this.spec)
+    });
+    for (const w of cascade.warnings) warn(w);
+    const changed = [];
+    let next = this.values;
+    for (const [path, v] of Object.entries(cascade.changes)) {
+      const old = deepGet(next, path);
+      if (deepEqual(old, v)) continue;
+      next = deepSet(next, path, v);
+      changed.push(path);
+    }
+    if (changed.length === 0) return;
+    this.values = next;
+    this.invalidateToQueryCache();
+    for (const path of changed) this.trie.notify(path);
+    this.persistToStorage(changed, options);
+  }
+  /** Boolean-flip helper. */
+  toggle(path, options) {
+    const current = this.getValue(path);
+    this.set(path, !current, options);
+  }
+  /** Push a value onto an array field. */
+  append(path, value, options) {
+    const current = this.getValue(path);
+    if (!Array.isArray(current)) return;
+    this.set(path, [...current, value], options);
+  }
+  /** Remove the first array element matching `value` by deepEqual. */
+  remove(path, value, options) {
+    const current = this.getValue(path);
+    if (!Array.isArray(current)) return;
+    const idx = current.findIndex((item) => deepEqual(item, value));
+    if (idx === -1) return;
+    this.set(path, [...current.slice(0, idx), ...current.slice(idx + 1)], options);
+  }
+  /** Remove the array element at the given index. */
+  removeAt(path, index, options) {
+    const current = this.getValue(path);
+    if (!Array.isArray(current)) return;
+    if (index < 0 || index >= current.length) return;
+    this.set(path, [...current.slice(0, index), ...current.slice(index + 1)], options);
+  }
+  cycle(path, valuesOrOptions, maybeOptions) {
+    let resolved;
+    let setOpts;
+    if (Array.isArray(valuesOrOptions)) {
+      resolved = valuesOrOptions;
+      setOpts = maybeOptions;
+    } else {
+      resolved = void 0;
+      setOpts = valuesOrOptions;
+    }
+    if (resolved === void 0) {
+      const fieldSpec = this.spec[path];
+      const derived = fieldSpec !== void 0 ? extractEnumValues(fieldSpec) : void 0;
+      if (!derived || derived.length === 0) {
+        throw new Error(
+          `Cannot derive enum values for params field '${path}'; pass values explicitly to cycle().`
+        );
+      }
+      resolved = derived;
+    }
+    if (resolved.length === 0) return;
+    const current = this.getValue(path);
+    const idx = resolved.findIndex((o) => deepEqual(o, current));
+    const next = idx === -1 ? resolved[0] : resolved[(idx + 1) % resolved.length];
+    this.set(path, next, setOpts);
+  }
+  /** Reset a single field to its default. */
+  clear(path, options) {
+    const def = deepGet(this.defaults, path);
+    this.set(path, def, options);
+  }
+  /** Reset all fields to defaults; optional partial overrides + SetOptions. */
+  reset(values, options) {
+    if (this.disposed) return;
+    const next = values ? { ...this.defaults, ...values } : { ...this.defaults };
+    const changed = Object.keys({ ...this.values, ...next });
+    this.values = next;
+    this.invalidateToQueryCache();
+    for (const path of changed) this.trie.notify(path);
+    const writeOptions = options?.history !== void 0 ? { history: options.history } : void 0;
+    void this.storage.clear?.([], writeOptions);
+    this.lastWritten = void 0;
+  }
+  // ─── Subscriptions ────────────────────────────────────────────────────
+  subscribe(path, listener) {
+    return this.trie.subscribe(path, listener);
+  }
+  // ─── URL helpers ──────────────────────────────────────────────────────
+  toQuery(overrides) {
+    const effective = overrides ? { ...this.values, ...overrides } : this.values;
+    if (!overrides && this.toQueryCache && this.toQueryCache.values === this.values) {
+      return this.toQueryCache.query;
+    }
+    const params = new URLSearchParams();
+    const keys = Object.keys(effective).sort();
+    for (const key of keys) {
+      const value = effective[key];
+      if (value === void 0 || value === null) continue;
+      const config = this.fieldConfigs[key];
+      const def = deepGet(this.defaults, key);
+      if (config?.omitWhenDefault && deepEqual(value, def)) continue;
+      params.set(key, defaultSerialize(value));
+    }
+    const str = params.toString();
+    const out = str ? `?${str}` : "";
+    if (!overrides) this.toQueryCache = { values: this.values, query: out };
+    return out;
+  }
+  href(overrides) {
+    if (!overrides) {
+      const query = this.toQuery();
+      const pathname2 = isClient ? window.location.pathname : "";
+      const cached = this.toQueryCache;
+      if (cached && cached.values === this.values && cached.href !== void 0) {
+        const expected = pathname2 + query;
+        if (cached.href === expected) return cached.href;
+      }
+      const out = pathname2 + query;
+      if (cached && cached.values === this.values) cached.href = out;
+      return out;
+    }
+    const pathname = isClient ? window.location.pathname : "";
+    return pathname + this.toQuery(overrides);
+  }
+  // ─── Disposal ─────────────────────────────────────────────────────────
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.storageUnsubscribe?.();
+    this.storageUnsubscribe = void 0;
+  }
+  // ─── Devtools / debugging escape hatch (v0.5) ─────────────────────────
+  /**
+   * Devtools / debugging escape hatch. Returns a frozen, defensive-copied
+   * snapshot of all internal state. Pure read — no side effects, no
+   * subscriptions registered.
+   *
+   * Uses `structuredClone` for the values + defaults deep-copy. Because
+   * params values round-trip through storage backends, they're already
+   * restricted to JSON-safe shapes — so `__introspect()` is safer here than
+   * on `FormStore`. Still: marked unstable via the `__` prefix; field set
+   * may grow over releases.
+   */
+  __introspect() {
+    const specTypes = {};
+    for (const [path, spec] of Object.entries(this.spec)) {
+      if (isPlainSpec(spec)) {
+        specTypes[path] = "plain";
+        continue;
+      }
+      if (spec?._def) {
+        specTypes[path] = "zod";
+        continue;
+      }
+      if (isStandardSchema(spec)) {
+        specTypes[path] = "standard-schema";
+        continue;
+      }
+      specTypes[path] = "plain";
+    }
+    let valuesClone;
+    let defaultsClone;
+    let lastWrittenClone;
+    try {
+      valuesClone = structuredClone(this.values);
+      defaultsClone = structuredClone(this.defaults);
+      lastWrittenClone = this.lastWritten ? structuredClone(this.lastWritten) : void 0;
+    } catch (err) {
+      throw new Error(
+        `ParamsStore.__introspect() failed: values contain non-cloneable data (functions, Symbols, DOM nodes are not allowed in params state). Original error: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    return Object.freeze({
+      values: valuesClone,
+      defaults: defaultsClone,
+      fieldsConfigured: Object.freeze({ ...this.fieldConfigs }),
+      fieldsBySpecType: Object.freeze(specTypes),
+      storageErrors: Object.freeze({ ...this.storageErrors }),
+      storage: Object.freeze({
+        name: this.storage.name,
+        clientOnly: this.storage.clientOnly === true,
+        hasReadAsync: this.storage.readAsync !== void 0,
+        hasSubscribe: this.storage.subscribe !== void 0,
+        hasClear: this.storage.clear !== void 0
+      }),
+      lastWritten: lastWrittenClone
+    });
+  }
+  // ─── Internals ────────────────────────────────────────────────────────
+  computeDefaults() {
+    const out = {};
+    for (const [key, fieldSpec] of Object.entries(this.spec)) {
+      const def = getDefault(fieldSpec);
+      if (def !== void 0) out[key] = def;
+    }
+    return out;
+  }
+  hydrateFromStorage() {
+    let raw;
+    try {
+      raw = this.storage.read();
+    } catch (err) {
+      this.storageErrorMap.set("__read__", err instanceof Error ? err.message : String(err));
+      return;
+    }
+    if (!raw) return;
+    for (const [key, rawValue] of Object.entries(raw)) {
+      const fieldSpec = this.spec[key];
+      if (!fieldSpec) continue;
+      const result = parseField(fieldSpec, rawValue);
+      if (result.ok && result.value !== void 0) {
+        ;
+        this.values[key] = result.value;
+      } else if (result.reason) {
+        this.storageErrorMap.set(key, result.reason);
+      }
+    }
+  }
+  persistToStorage(changed, options) {
+    const filtered = {};
+    for (const path of changed) {
+      const value = this.values[path];
+      const config = this.fieldConfigs[path];
+      const def = deepGet(this.defaults, path);
+      if (config?.omitWhenDefault && deepEqual(value, def)) {
+        filtered[path] = void 0;
+      } else {
+        filtered[path] = value;
+      }
+    }
+    const writeOptions = options?.history !== void 0 ? { history: options.history } : void 0;
+    this.lastWritten = { ...this.values };
+    try {
+      const result = this.storage.write(filtered, changed, writeOptions);
+      if (result && typeof result.then === "function") {
+        ;
+        result.catch(() => void 0);
+      }
+    } catch {
+    }
+  }
+  onExternalChange(raw) {
+    if (this.disposed) return;
+    if (this.lastWritten && deepEqual(raw, this.lastWritten)) return;
+    const changed = [];
+    let next = this.values;
+    for (const [key, rawValue] of Object.entries(raw)) {
+      const fieldSpec = this.spec[key];
+      if (!fieldSpec) continue;
+      const result = parseField(fieldSpec, rawValue);
+      const newValue = result.ok ? result.value : deepGet(this.defaults, key);
+      const oldValue = deepGet(next, key);
+      if (deepEqual(oldValue, newValue)) continue;
+      next = deepSet(next, key, newValue);
+      changed.push(key);
+      if (!result.ok && result.reason) {
+        this.storageErrorMap.set(key, result.reason);
+      } else {
+        this.storageErrorMap.delete(key);
+      }
+    }
+    if (changed.length === 0) return;
+    this.values = next;
+    this.invalidateToQueryCache();
+    for (const path of changed) this.trie.notify(path);
+  }
+  invalidateToQueryCache() {
+    this.toQueryCache = void 0;
+  }
+};
+
+// src/store-cache.ts
+var cache = /* @__PURE__ */ new WeakMap();
+var seenNames = /* @__PURE__ */ new Map();
+function acquire(def) {
+  warnOnDuplicateName(def);
+  let entry = cache.get(def);
+  if (!entry) {
+    entry = {
+      store: new ParamsStore(def),
+      refCount: 0,
+      disposalQueued: false
+    };
+    cache.set(def, entry);
+  } else {
+    entry.disposalQueued = false;
+  }
+  entry.refCount++;
+  return entry.store;
+}
+function release(def) {
+  const entry = cache.get(def);
+  if (!entry) return;
+  entry.refCount--;
+  if (entry.refCount > 0) return;
+  entry.disposalQueued = true;
+  queueMicrotask(() => {
+    if (!entry.disposalQueued) return;
+    entry.disposalQueued = false;
+    disposeAndClear(def, entry);
+  });
+}
+function disposeAndClear(def, entry) {
+  entry.store.dispose();
+  cache.delete(def);
+  if (def.name !== void 0 && seenNames.get(def.name) === def) {
+    seenNames.delete(def.name);
+  }
+}
+function getCachedStore(def) {
+  let entry = cache.get(def);
+  if (!entry) {
+    entry = {
+      store: new ParamsStore(def),
+      refCount: 0,
+      disposalQueued: false
+    };
+    cache.set(def, entry);
+  }
+  return entry.store;
+}
+function releaseCachedStore(def) {
+  const entry = cache.get(def);
+  if (!entry) {
+    if (def.name !== void 0 && seenNames.get(def.name) === def) {
+      seenNames.delete(def.name);
+    }
+    return;
+  }
+  disposeAndClear(def, entry);
+}
+function warnOnDuplicateName(def) {
+  if (def.name === void 0) return;
+  const existing = seenNames.get(def.name);
+  if (existing !== void 0 && existing !== def) {
+    warn(
+      `Duplicate definition name '${def.name}' detected. Names must be unique across definitions for v0.2 SSR snapshot keys.`
+    );
+    return;
+  }
+  seenNames.set(def.name, def);
+}
+
+export {
+  ParamsStore,
+  acquire,
+  release,
+  getCachedStore,
+  releaseCachedStore
+};
+//# sourceMappingURL=chunk-43PUAYQP.js.map