@victorylabs/params 0.2.0 → 0.3.0

package/dist/react.cjs

@@ -20,14 +20,30 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/react/index.ts
 var react_exports = {};
 __export(react_exports, {
+  useDebouncedValue: () => useDebouncedValue,
   useFieldInput: () => useFieldInput,
   useFieldValue: () => useFieldValue,
   useParams: () => useParams
 });
 module.exports = __toCommonJS(react_exports);
 
+// src/react/use-debounced-value.ts
+var import_react = require("react");
+function useDebouncedValue(value, ms) {
+  const [debounced, setDebounced] = (0, import_react.useState)(value);
+  (0, import_react.useEffect)(() => {
+    if (ms <= 0) {
+      setDebounced(value);
+      return;
+    }
+    const id = setTimeout(() => setDebounced(value), ms);
+    return () => clearTimeout(id);
+  }, [value, ms]);
+  return debounced;
+}
+
 // src/react/use-field-input.tsx
-var import_react2 = require("react");
+var import_react3 = require("react");
 
 // src/schema.ts
 function isStandardSchema(spec) {
@@ -121,10 +137,10 @@ function extractEnumValues(spec) {
 }
 
 // src/react/use-field-value.ts
-var import_react = require("react");
+var import_react2 = require("react");
 function useFieldValue(store, path) {
-  const [, forceRender] = (0, import_react.useReducer)((tick) => tick + 1, 0);
-  (0, import_react.useEffect)(() => store.subscribe(path, forceRender), [store, path]);
+  const [, forceRender] = (0, import_react2.useReducer)((tick) => tick + 1, 0);
+  (0, import_react2.useEffect)(() => store.subscribe(path, forceRender), [store, path]);
   return store.getValue(path);
 }
 
@@ -133,10 +149,10 @@ function useFieldInput(store, path) {
   const storeValue = useFieldValue(store, path);
   const config = store.getFieldConfig(path);
   const debounceMs = config?.debounce ?? 0;
-  const [shadow, setShadow] = (0, import_react2.useState)(null);
-  const debouncerRef = (0, import_react2.useRef)(null);
-  const lastStoreValueRef = (0, import_react2.useRef)(storeValue);
-  (0, import_react2.useEffect)(() => {
+  const [shadow, setShadow] = (0, import_react3.useState)(null);
+  const debouncerRef = (0, import_react3.useRef)(null);
+  const lastStoreValueRef = (0, import_react3.useRef)(storeValue);
+  (0, import_react3.useEffect)(() => {
     if (Object.is(lastStoreValueRef.current, storeValue)) return;
     lastStoreValueRef.current = storeValue;
     if (shadow !== null && shadow !== defaultSerialize(storeValue)) {
@@ -147,19 +163,19 @@ function useFieldInput(store, path) {
   if (debounceMs > 0 && debouncerRef.current === null) {
     debouncerRef.current = createDebouncer(store, path, debounceMs, () => setShadow(null));
   }
-  const onChange = (0, import_react2.useCallback)(
+  const onChange = (0, import_react3.useCallback)(
     (event) => {
       const next = event.target.value;
       if (debounceMs > 0) {
         setShadow(next);
         debouncerRef.current?.trigger(next);
       } else {
-        store.set(path, next);
+        store.setField(path, next);
       }
     },
     [store, path, debounceMs]
   );
-  const onBlur = (0, import_react2.useCallback)(() => {
+  const onBlur = (0, import_react3.useCallback)(() => {
     debouncerRef.current?.flush();
   }, []);
   return {
@@ -174,7 +190,7 @@ function createDebouncer(store, path, ms, onCommit) {
   let pendingValue = null;
   const commit = () => {
     if (pendingValue !== null) {
-      store.set(path, pendingValue);
+      store.setField(path, pendingValue);
       pendingValue = null;
       onCommit();
     }
@@ -202,10 +218,10 @@ function createDebouncer(store, path, ms, onCommit) {
 }
 
 // src/react/use-params.tsx
-var import_react4 = require("react");
+var import_react5 = require("react");
 
 // src/react/use-shared-store.ts
-var import_react3 = require("react");
+var import_react4 = require("react");
 
 // src/dev.ts
 var isDev = (() => {
@@ -485,17 +501,43 @@ var ParamsStore = class {
   getFieldConfig(path) {
     return this.fieldConfigs[path];
   }
-  set(pathOrPartial, valueOrOptions, maybeOptions) {
+  // ─── Writes ───────────────────────────────────────────────────────────
+  /**
+   * Apply a partial update — write multiple fields at once.
+   *
+   * `set(partial)` is the canonical write form. The path-and-value form
+   * (`set(path, value)` historically) is now `setField(path, value)` —
+   * see {@link setField}. The split keeps `set`'s single-signature
+   * inference clean for the common `set({ [key]: value })` pattern, which
+   * previously required `as Partial<T>` casts because TypeScript couldn't
+   * resolve the overload from a generic-keyed object literal.
+   *
+   * @example
+   * ```ts
+   * p.set({ page: 1, sort: 'updated' })
+   * p.set({ [key]: value })   // works without a cast now
+   * ```
+   */
+  set(partial, options) {
     if (this.disposed) return;
-    let updates;
-    let options;
-    if (typeof pathOrPartial === "string") {
-      updates = { [pathOrPartial]: valueOrOptions };
-      options = maybeOptions;
-    } else {
-      updates = pathOrPartial;
-      options = valueOrOptions;
-    }
+    this.applyUpdates(partial, options);
+  }
+  /**
+   * Write a single field by path. Equivalent to `set({ [path]: value })`
+   * but skips the object-literal allocation and avoids the inference issue
+   * that motivated splitting the API.
+   *
+   * @example
+   * ```ts
+   * p.setField('query', 'react')
+   * p.setField('filters.tags', ['ts', 'react'])
+   * ```
+   */
+  setField(path, value, options) {
+    if (this.disposed) return;
+    this.applyUpdates({ [path]: value }, options);
+  }
+  applyUpdates(updates, options) {
     const initialChanges = {};
     for (const [path, v] of Object.entries(updates)) {
       const old = deepGet(this.values, path);
@@ -527,13 +569,13 @@ var ParamsStore = class {
   /** Boolean-flip helper. */
   toggle(path, options) {
     const current = this.getValue(path);
-    this.set(path, !current, options);
+    this.setField(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);
+    this.setField(path, [...current, value], options);
   }
   /** Remove the first array element matching `value` by deepEqual. */
   remove(path, value, options) {
@@ -541,14 +583,14 @@ var ParamsStore = class {
     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);
+    this.setField(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);
+    this.setField(path, [...current.slice(0, index), ...current.slice(index + 1)], options);
   }
   cycle(path, valuesOrOptions, maybeOptions) {
     let resolved;
@@ -574,12 +616,12 @@ var ParamsStore = class {
     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);
+    this.setField(path, next, setOpts);
   }
   /** Reset a single field to its default. */
   clear(path, options) {
     const def = deepGet(this.defaults, path);
-    this.set(path, def, options);
+    this.setField(path, def, options);
   }
   /** Reset all fields to defaults; optional partial overrides + SetOptions. */
   reset(values, options) {
@@ -833,11 +875,11 @@ function warnOnDuplicateName(def) {
 
 // src/react/use-shared-store.ts
 function useSharedStore(def) {
-  const storeRef = (0, import_react3.useRef)(null);
+  const storeRef = (0, import_react4.useRef)(null);
   if (storeRef.current === null) {
     storeRef.current = acquire(def);
   }
-  (0, import_react3.useEffect)(
+  (0, import_react4.useEffect)(
     () => () => {
       release(def);
       storeRef.current = null;
@@ -850,35 +892,33 @@ function useSharedStore(def) {
 // src/react/use-params.tsx
 function useParams(def) {
   const store = useSharedStore(def);
-  const [, forceRender] = (0, import_react4.useReducer)((tick) => tick + 1, 0);
-  (0, import_react4.useEffect)(() => store.subscribe("", forceRender), [store]);
-  const set = (0, import_react4.useCallback)(
-    ((pathOrPartial, valueOrOptions, maybeOptions) => {
-      if (typeof pathOrPartial === "string") {
-        store.set(pathOrPartial, valueOrOptions, maybeOptions);
-      } else {
-        store.set(pathOrPartial, valueOrOptions);
-      }
-    }),
+  const [, forceRender] = (0, import_react5.useReducer)((tick) => tick + 1, 0);
+  (0, import_react5.useEffect)(() => store.subscribe("", forceRender), [store]);
+  const set = (0, import_react5.useCallback)(
+    (partial, options) => store.set(partial, options),
+    [store]
+  );
+  const setField = (0, import_react5.useCallback)(
+    (path, value2, options) => store.setField(path, value2, options),
     [store]
   );
-  const toggle = (0, import_react4.useCallback)(
+  const toggle = (0, import_react5.useCallback)(
     (path, options) => store.toggle(path, options),
     [store]
   );
-  const append = (0, import_react4.useCallback)(
+  const append = (0, import_react5.useCallback)(
     (path, value2, options) => store.append(path, value2, options),
     [store]
   );
-  const removeFn = (0, import_react4.useCallback)(
+  const removeFn = (0, import_react5.useCallback)(
     (path, value2, options) => store.remove(path, value2, options),
     [store]
   );
-  const removeAt = (0, import_react4.useCallback)(
+  const removeAt = (0, import_react5.useCallback)(
     (path, index, options) => store.removeAt(path, index, options),
     [store]
   );
-  const cycle = (0, import_react4.useCallback)(
+  const cycle = (0, import_react5.useCallback)(
     ((path, valuesOrOptions, maybeOptions) => {
       if (Array.isArray(valuesOrOptions)) {
         store.cycle(path, valuesOrOptions, maybeOptions);
@@ -890,32 +930,36 @@ function useParams(def) {
     }),
     [store]
   );
-  const clear = (0, import_react4.useCallback)(
+  const clear = (0, import_react5.useCallback)(
     (path, options) => store.clear(path, options),
     [store]
   );
-  const reset = (0, import_react4.useCallback)(
+  const reset = (0, import_react5.useCallback)(
     (values, options) => store.reset(values, options),
     [store]
   );
-  const subscribe = (0, import_react4.useCallback)(
+  const subscribe = (0, import_react5.useCallback)(
     (path, listener) => store.subscribe(path, listener),
     [store]
   );
-  const toQuery = (0, import_react4.useCallback)(
+  const toQuery = (0, import_react5.useCallback)(
     (overrides) => store.toQuery(overrides),
     [store]
   );
-  const href = (0, import_react4.useCallback)((overrides) => store.href(overrides), [store]);
+  const href = (0, import_react5.useCallback)((overrides) => store.href(overrides), [store]);
   const value = (path) => useFieldValue(store, path);
-  const deferred = (path) => (0, import_react4.useDeferredValue)(useFieldValue(store, path));
+  const deferred = (path) => (0, import_react5.useDeferredValue)(useFieldValue(store, path));
   const input = (path) => useFieldInput(store, path);
   return {
+    // Cast: store.getValues() returns Partial<T> for the storage layer's
+    // sake, but every field in ParamsDefinition declares a default so the
+    // hydrated view is structurally complete. See ParamsController.values.
     values: store.getValues(),
     value,
     deferred,
     input,
     set,
+    setField,
     toggle,
     append,
     remove: removeFn,
@@ -931,6 +975,7 @@ function useParams(def) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  useDebouncedValue,
   useFieldInput,
   useFieldValue,
   useParams