kitzo 2.5.3 → 2.5.5

package/dist/index.d.ts

@@ -51,6 +51,13 @@ declare type DebounceOptions = {
 
 declare type Options = ToastOptionsWithoutType;
 
+declare type Options_2<T> = {
+    /** Milliseconds to debounce writes to localStorage (default: 0 — no debounce). */
+    debounceMs?: number;
+    /** Called once after the first value is read from localStorage on mount. */
+    onMount?: (value: T) => void;
+};
+
 declare type PromiseToastFn = <T, E = unknown>(promise: Promise<T>, msgs: PromiseToastMsgs<T, E>, options?: PromiseToastOptions) => Promise<T>;
 
 declare type PromiseToastMsgs<T, E = unknown> = {
@@ -161,13 +168,25 @@ export declare function useDebouncedCallback<Args extends unknown[]>(callback: (
 
 /**
  * A custom hook that manages a stateful value in `localStorage`,
- * ensuring synchronization across multiple tabs and components.
+ * with full SSR safety and cross-tab synchronization.
+ *
+ * The hook uses a two-phase approach: the server and first client render
+ * always use `initialValue` (preventing hydration mismatches), and the
+ * real localStorage value is synced in after mount.
+ *
+ * - State is updated immediately on every `setValue` call for a responsive UI.
+ * - Writes to `localStorage` are debounced by `options.debounceMs` ms.
+ * - `options.onMount` is called exactly once with the first value read from storage.
+ *
  * @example
- * const [theme, setTheme] = useLocalStorage<'light' | 'dark'>('ui-theme', 'light');
+ * const [theme, setTheme] = useLocalStorage<'light' | 'dark'>('ui-theme', 'light', {
+ *   debounceMs: 300,
+ *   onMount: (v) => console.log('loaded from storage:', v),
+ * });
  * // Supports functional updates:
  * setTheme(prev => prev === 'light' ? 'dark' : 'light');
  */
-export declare function useLocalStorage<T>(key: string, initialValue: T): [T, Dispatch<SetStateAction<T>>];
+export declare function useLocalStorage<T>(key: string, initialValue: T, options?: Options_2<T>): [T, Dispatch<SetStateAction<T>>];
 
 export declare function useThrottle<T>(value: T, delay?: number): T;
 

package/dist/react/hooks/useLocalStorage.js

@@ -1,34 +1,42 @@
-import { useCallback as c, useState as w, useEffect as i } from "react";
-function u(t, r) {
-  const n = c(() => {
-    if (typeof window > "u")
-      return r;
+import o from "react";
+function E(r, c, f) {
+  const g = f ?? {}, { debounceMs: s = 0, onMount: l } = g, i = o.useRef(l);
+  o.useEffect(() => {
+    i.current = l;
+  });
+  const [a, u] = o.useState(c), d = o.useCallback(() => {
     try {
-      const e = window.localStorage.getItem(t);
-      return e ? JSON.parse(e) : r;
+      const e = window.localStorage.getItem(r);
+      return e ? JSON.parse(e) : c;
     } catch (e) {
-      return console.warn(`Error reading localStorage key “${t}”:`, e), r;
+      return console.warn(`Error reading localStorage key "${r}":`, e), c;
     }
-  }, [t, r]), [a, s] = w(n), d = c(
+  }, [r, c]), n = o.useRef(
+    null
+  ), S = o.useCallback(
     (e) => {
       try {
-        const o = e instanceof Function ? e(a) : e;
-        s(o), typeof window < "u" && (window.localStorage.setItem(t, JSON.stringify(o)), window.dispatchEvent(new Event("local-storage-update")));
-      } catch (o) {
-        console.warn(`Error setting localStorage key “${t}”:`, o);
+        const t = e instanceof Function ? e(a) : e;
+        u(t), typeof window < "u" && (n.current !== null && clearTimeout(n.current), s > 0 ? n.current = setTimeout(() => {
+          window.localStorage.setItem(r, JSON.stringify(t)), window.dispatchEvent(new Event("local-storage-update")), n.current = null;
+        }, s) : (window.localStorage.setItem(r, JSON.stringify(t)), window.dispatchEvent(new Event("local-storage-update"))));
+      } catch (t) {
+        console.warn(`Error setting localStorage key "${r}":`, t);
       }
     },
-    [t, a]
+    [r, a, s]
   );
-  return i(() => {
-    const e = (o) => {
-      o.key && o.key !== t || s(n());
+  return o.useEffect(() => {
+    const e = d();
+    u(e), i.current?.(e);
+    const t = (w) => {
+      w.key && w.key !== r || u(d());
     };
-    return window.addEventListener("storage", e), window.addEventListener("local-storage-update", e), () => {
-      window.removeEventListener("storage", e), window.removeEventListener("local-storage-update", e);
+    return window.addEventListener("storage", t), window.addEventListener("local-storage-update", t), () => {
+      n.current !== null && clearTimeout(n.current), window.removeEventListener("storage", t), window.removeEventListener("local-storage-update", t);
     };
-  }, [t, n]), [a, d];
+  }, [r]), [a, S];
 }
 export {
-  u as useLocalStorage
+  E as useLocalStorage
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kitzo",
-  "version": "2.5.3",
+  "version": "2.5.5",
   "description": "A lightweight React micro-utility.",
   "type": "module",
   "files": [