@usefy/use-local-storage 0.0.2

package/dist/index.d.mts

@@ -0,0 +1,109 @@
+/**
+ * Type for initial value that can be a value or a function returning a value (lazy initialization)
+ */
+type InitialValue<T> = T | (() => T);
+/**
+ * Options for useLocalStorage hook
+ */
+interface UseLocalStorageOptions<T> {
+    /**
+     * Custom serializer function for converting value to string
+     * @default JSON.stringify
+     */
+    serializer?: (value: T) => string;
+    /**
+     * Custom deserializer function for parsing stored string to value
+     * @default JSON.parse
+     */
+    deserializer?: (value: string) => T;
+    /**
+     * Whether to sync value across browser tabs via storage event
+     * @default true
+     */
+    syncTabs?: boolean;
+    /**
+     * Callback function called when an error occurs
+     */
+    onError?: (error: Error) => void;
+}
+/**
+ * Return type for useLocalStorage hook - tuple similar to useState
+ */
+type UseLocalStorageReturn<T> = readonly [
+    /** Current stored value */
+    T,
+    /** Function to update the value (same signature as useState setter) */
+    React.Dispatch<React.SetStateAction<T>>,
+    /** Function to remove the value from localStorage */
+    () => void
+];
+/**
+ * A hook for persisting state in localStorage with automatic synchronization.
+ * Works like useState but persists the value in localStorage.
+ *
+ * @template T - The type of the stored value
+ * @param key - The localStorage key to store the value under
+ * @param initialValue - Initial value or function returning initial value (lazy initialization)
+ * @param options - Configuration options for serialization, sync, and error handling
+ * @returns A tuple of [storedValue, setValue, removeValue]
+ *
+ * @example
+ * ```tsx
+ * // Basic usage with string
+ * function ThemeToggle() {
+ *   const [theme, setTheme, removeTheme] = useLocalStorage('theme', 'light');
+ *
+ *   return (
+ *     <div>
+ *       <p>Current theme: {theme}</p>
+ *       <button onClick={() => setTheme('dark')}>Dark</button>
+ *       <button onClick={() => setTheme('light')}>Light</button>
+ *       <button onClick={removeTheme}>Reset</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With object type
+ * interface UserSettings {
+ *   notifications: boolean;
+ *   language: string;
+ * }
+ *
+ * const [settings, setSettings] = useLocalStorage<UserSettings>('settings', {
+ *   notifications: true,
+ *   language: 'en',
+ * });
+ *
+ * // Functional update
+ * setSettings(prev => ({ ...prev, notifications: false }));
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With lazy initialization
+ * const [config, setConfig] = useLocalStorage('config', () => computeExpensiveDefault());
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom serializer/deserializer
+ * const [date, setDate] = useLocalStorage<Date>('lastVisit', new Date(), {
+ *   serializer: (d) => d.toISOString(),
+ *   deserializer: (s) => new Date(s),
+ * });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With error handling
+ * const [value, setValue] = useLocalStorage('key', 'default', {
+ *   onError: (error) => console.error('Storage error:', error),
+ * });
+ * ```
+ */
+declare function useLocalStorage<T>(key: string, initialValue: InitialValue<T>, options?: UseLocalStorageOptions<T>): UseLocalStorageReturn<T>;
+
+export { type InitialValue, type UseLocalStorageOptions, type UseLocalStorageReturn, useLocalStorage };

package/dist/index.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Type for initial value that can be a value or a function returning a value (lazy initialization)
+ */
+type InitialValue<T> = T | (() => T);
+/**
+ * Options for useLocalStorage hook
+ */
+interface UseLocalStorageOptions<T> {
+    /**
+     * Custom serializer function for converting value to string
+     * @default JSON.stringify
+     */
+    serializer?: (value: T) => string;
+    /**
+     * Custom deserializer function for parsing stored string to value
+     * @default JSON.parse
+     */
+    deserializer?: (value: string) => T;
+    /**
+     * Whether to sync value across browser tabs via storage event
+     * @default true
+     */
+    syncTabs?: boolean;
+    /**
+     * Callback function called when an error occurs
+     */
+    onError?: (error: Error) => void;
+}
+/**
+ * Return type for useLocalStorage hook - tuple similar to useState
+ */
+type UseLocalStorageReturn<T> = readonly [
+    /** Current stored value */
+    T,
+    /** Function to update the value (same signature as useState setter) */
+    React.Dispatch<React.SetStateAction<T>>,
+    /** Function to remove the value from localStorage */
+    () => void
+];
+/**
+ * A hook for persisting state in localStorage with automatic synchronization.
+ * Works like useState but persists the value in localStorage.
+ *
+ * @template T - The type of the stored value
+ * @param key - The localStorage key to store the value under
+ * @param initialValue - Initial value or function returning initial value (lazy initialization)
+ * @param options - Configuration options for serialization, sync, and error handling
+ * @returns A tuple of [storedValue, setValue, removeValue]
+ *
+ * @example
+ * ```tsx
+ * // Basic usage with string
+ * function ThemeToggle() {
+ *   const [theme, setTheme, removeTheme] = useLocalStorage('theme', 'light');
+ *
+ *   return (
+ *     <div>
+ *       <p>Current theme: {theme}</p>
+ *       <button onClick={() => setTheme('dark')}>Dark</button>
+ *       <button onClick={() => setTheme('light')}>Light</button>
+ *       <button onClick={removeTheme}>Reset</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With object type
+ * interface UserSettings {
+ *   notifications: boolean;
+ *   language: string;
+ * }
+ *
+ * const [settings, setSettings] = useLocalStorage<UserSettings>('settings', {
+ *   notifications: true,
+ *   language: 'en',
+ * });
+ *
+ * // Functional update
+ * setSettings(prev => ({ ...prev, notifications: false }));
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With lazy initialization
+ * const [config, setConfig] = useLocalStorage('config', () => computeExpensiveDefault());
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom serializer/deserializer
+ * const [date, setDate] = useLocalStorage<Date>('lastVisit', new Date(), {
+ *   serializer: (d) => d.toISOString(),
+ *   deserializer: (s) => new Date(s),
+ * });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With error handling
+ * const [value, setValue] = useLocalStorage('key', 'default', {
+ *   onError: (error) => console.error('Storage error:', error),
+ * });
+ * ```
+ */
+declare function useLocalStorage<T>(key: string, initialValue: InitialValue<T>, options?: UseLocalStorageOptions<T>): UseLocalStorageReturn<T>;
+
+export { type InitialValue, type UseLocalStorageOptions, type UseLocalStorageReturn, useLocalStorage };

package/dist/index.js

@@ -0,0 +1,136 @@
+"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/index.ts
+var index_exports = {};
+__export(index_exports, {
+  useLocalStorage: () => useLocalStorage
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/useLocalStorage.ts
+var import_react = require("react");
+function resolveInitialValue(initialValue) {
+  return typeof initialValue === "function" ? initialValue() : initialValue;
+}
+function useLocalStorage(key, initialValue, options = {}) {
+  const {
+    serializer = JSON.stringify,
+    deserializer = JSON.parse,
+    syncTabs = true,
+    onError
+  } = options;
+  const serializerRef = (0, import_react.useRef)(serializer);
+  const deserializerRef = (0, import_react.useRef)(deserializer);
+  const onErrorRef = (0, import_react.useRef)(onError);
+  serializerRef.current = serializer;
+  deserializerRef.current = deserializer;
+  onErrorRef.current = onError;
+  const initialValueRef = (0, import_react.useRef)(initialValue);
+  initialValueRef.current = initialValue;
+  const isClient = typeof window !== "undefined";
+  const [storedValue, setStoredValue] = (0, import_react.useState)(() => {
+    if (!isClient) {
+      return resolveInitialValue(initialValue);
+    }
+    try {
+      const item = window.localStorage.getItem(key);
+      if (item !== null) {
+        return deserializerRef.current(item);
+      }
+      return resolveInitialValue(initialValue);
+    } catch (error) {
+      onErrorRef.current?.(error);
+      return resolveInitialValue(initialValue);
+    }
+  });
+  const storedValueRef = (0, import_react.useRef)(storedValue);
+  storedValueRef.current = storedValue;
+  const setValue = (0, import_react.useCallback)(
+    (value) => {
+      try {
+        const currentValue = storedValueRef.current;
+        const valueToStore = value instanceof Function ? value(currentValue) : value;
+        setStoredValue(valueToStore);
+        if (typeof window !== "undefined") {
+          window.localStorage.setItem(
+            key,
+            serializerRef.current(valueToStore)
+          );
+        }
+      } catch (error) {
+        onErrorRef.current?.(error);
+      }
+    },
+    [key]
+  );
+  const removeValue = (0, import_react.useCallback)(() => {
+    try {
+      const initial = resolveInitialValue(initialValueRef.current);
+      setStoredValue(initial);
+      if (typeof window !== "undefined") {
+        window.localStorage.removeItem(key);
+      }
+    } catch (error) {
+      onErrorRef.current?.(error);
+    }
+  }, [key]);
+  (0, import_react.useEffect)(() => {
+    if (!isClient || !syncTabs) {
+      return;
+    }
+    const handleStorageChange = (event) => {
+      if (event.key !== key) {
+        return;
+      }
+      if (event.newValue !== null) {
+        try {
+          setStoredValue(deserializerRef.current(event.newValue));
+        } catch {
+          setStoredValue(resolveInitialValue(initialValueRef.current));
+        }
+      } else {
+        setStoredValue(resolveInitialValue(initialValueRef.current));
+      }
+    };
+    window.addEventListener("storage", handleStorageChange);
+    return () => window.removeEventListener("storage", handleStorageChange);
+  }, [key, syncTabs, isClient]);
+  (0, import_react.useEffect)(() => {
+    if (!isClient) {
+      return;
+    }
+    try {
+      const item = window.localStorage.getItem(key);
+      if (item !== null) {
+        setStoredValue(deserializerRef.current(item));
+      } else {
+        setStoredValue(resolveInitialValue(initialValueRef.current));
+      }
+    } catch {
+      setStoredValue(resolveInitialValue(initialValueRef.current));
+    }
+  }, [key]);
+  return [storedValue, setValue, removeValue];
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useLocalStorage
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/useLocalStorage.ts"],"sourcesContent":["export {\r\n  useLocalStorage,\r\n  type UseLocalStorageOptions,\r\n  type UseLocalStorageReturn,\r\n  type InitialValue,\r\n} from \"./useLocalStorage\";\r\n","import { useCallback, useEffect, useRef, useState } from \"react\";\r\n\r\n/**\r\n * Type for initial value that can be a value or a function returning a value (lazy initialization)\r\n */\r\nexport type InitialValue<T> = T | (() => T);\r\n\r\n/**\r\n * Options for useLocalStorage hook\r\n */\r\nexport interface UseLocalStorageOptions<T> {\r\n  /**\r\n   * Custom serializer function for converting value to string\r\n   * @default JSON.stringify\r\n   */\r\n  serializer?: (value: T) => string;\r\n  /**\r\n   * Custom deserializer function for parsing stored string to value\r\n   * @default JSON.parse\r\n   */\r\n  deserializer?: (value: string) => T;\r\n  /**\r\n   * Whether to sync value across browser tabs via storage event\r\n   * @default true\r\n   */\r\n  syncTabs?: boolean;\r\n  /**\r\n   * Callback function called when an error occurs\r\n   */\r\n  onError?: (error: Error) => void;\r\n}\r\n\r\n/**\r\n * Return type for useLocalStorage hook - tuple similar to useState\r\n */\r\nexport type UseLocalStorageReturn<T> = readonly [\r\n  /** Current stored value */\r\n  T,\r\n  /** Function to update the value (same signature as useState setter) */\r\n  React.Dispatch<React.SetStateAction<T>>,\r\n  /** Function to remove the value from localStorage */\r\n  () => void\r\n];\r\n\r\n/**\r\n * Helper function to resolve initial value (supports lazy initialization)\r\n */\r\nfunction resolveInitialValue<T>(initialValue: InitialValue<T>): T {\r\n  return typeof initialValue === \"function\"\r\n    ? (initialValue as () => T)()\r\n    : initialValue;\r\n}\r\n\r\n/**\r\n * A hook for persisting state in localStorage with automatic synchronization.\r\n * Works like useState but persists the value in localStorage.\r\n *\r\n * @template T - The type of the stored value\r\n * @param key - The localStorage key to store the value under\r\n * @param initialValue - Initial value or function returning initial value (lazy initialization)\r\n * @param options - Configuration options for serialization, sync, and error handling\r\n * @returns A tuple of [storedValue, setValue, removeValue]\r\n *\r\n * @example\r\n * ```tsx\r\n * // Basic usage with string\r\n * function ThemeToggle() {\r\n *   const [theme, setTheme, removeTheme] = useLocalStorage('theme', 'light');\r\n *\r\n *   return (\r\n *     <div>\r\n *       <p>Current theme: {theme}</p>\r\n *       <button onClick={() => setTheme('dark')}>Dark</button>\r\n *       <button onClick={() => setTheme('light')}>Light</button>\r\n *       <button onClick={removeTheme}>Reset</button>\r\n *     </div>\r\n *   );\r\n * }\r\n * ```\r\n *\r\n * @example\r\n * ```tsx\r\n * // With object type\r\n * interface UserSettings {\r\n *   notifications: boolean;\r\n *   language: string;\r\n * }\r\n *\r\n * const [settings, setSettings] = useLocalStorage<UserSettings>('settings', {\r\n *   notifications: true,\r\n *   language: 'en',\r\n * });\r\n *\r\n * // Functional update\r\n * setSettings(prev => ({ ...prev, notifications: false }));\r\n * ```\r\n *\r\n * @example\r\n * ```tsx\r\n * // With lazy initialization\r\n * const [config, setConfig] = useLocalStorage('config', () => computeExpensiveDefault());\r\n * ```\r\n *\r\n * @example\r\n * ```tsx\r\n * // With custom serializer/deserializer\r\n * const [date, setDate] = useLocalStorage<Date>('lastVisit', new Date(), {\r\n *   serializer: (d) => d.toISOString(),\r\n *   deserializer: (s) => new Date(s),\r\n * });\r\n * ```\r\n *\r\n * @example\r\n * ```tsx\r\n * // With error handling\r\n * const [value, setValue] = useLocalStorage('key', 'default', {\r\n *   onError: (error) => console.error('Storage error:', error),\r\n * });\r\n * ```\r\n */\r\nexport function useLocalStorage<T>(\r\n  key: string,\r\n  initialValue: InitialValue<T>,\r\n  options: UseLocalStorageOptions<T> = {}\r\n): UseLocalStorageReturn<T> {\r\n  const {\r\n    serializer = JSON.stringify,\r\n    deserializer = JSON.parse,\r\n    syncTabs = true,\r\n    onError,\r\n  } = options;\r\n\r\n  // Store options in refs for stable references and access to latest values\r\n  const serializerRef = useRef(serializer);\r\n  const deserializerRef = useRef(deserializer);\r\n  const onErrorRef = useRef(onError);\r\n  serializerRef.current = serializer;\r\n  deserializerRef.current = deserializer;\r\n  onErrorRef.current = onError;\r\n\r\n  // Store initialValue in ref for use in removeValue and storage event handler\r\n  const initialValueRef = useRef(initialValue);\r\n  initialValueRef.current = initialValue;\r\n\r\n  // SSR check - check once at module level for consistency\r\n  const isClient = typeof window !== \"undefined\";\r\n\r\n  // Lazy initialization with localStorage read\r\n  const [storedValue, setStoredValue] = useState<T>(() => {\r\n    if (!isClient) {\r\n      return resolveInitialValue(initialValue);\r\n    }\r\n\r\n    try {\r\n      const item = window.localStorage.getItem(key);\r\n      if (item !== null) {\r\n        return deserializerRef.current(item);\r\n      }\r\n      return resolveInitialValue(initialValue);\r\n    } catch (error) {\r\n      onErrorRef.current?.(error as Error);\r\n      return resolveInitialValue(initialValue);\r\n    }\r\n  });\r\n\r\n  // Store current value in ref for stable setValue reference\r\n  const storedValueRef = useRef<T>(storedValue);\r\n  storedValueRef.current = storedValue;\r\n\r\n  // setValue - stable reference (only depends on key)\r\n  const setValue = useCallback<React.Dispatch<React.SetStateAction<T>>>(\r\n    (value) => {\r\n      try {\r\n        const currentValue = storedValueRef.current;\r\n        const valueToStore =\r\n          value instanceof Function ? value(currentValue) : value;\r\n\r\n        setStoredValue(valueToStore);\r\n\r\n        if (typeof window !== \"undefined\") {\r\n          window.localStorage.setItem(\r\n            key,\r\n            serializerRef.current(valueToStore)\r\n          );\r\n        }\r\n      } catch (error) {\r\n        onErrorRef.current?.(error as Error);\r\n      }\r\n    },\r\n    [key]\r\n  );\r\n\r\n  // removeValue - stable reference\r\n  const removeValue = useCallback(() => {\r\n    try {\r\n      const initial = resolveInitialValue(initialValueRef.current);\r\n      setStoredValue(initial);\r\n\r\n      if (typeof window !== \"undefined\") {\r\n        window.localStorage.removeItem(key);\r\n      }\r\n    } catch (error) {\r\n      onErrorRef.current?.(error as Error);\r\n    }\r\n  }, [key]);\r\n\r\n  // Cross-tab synchronization via storage event\r\n  useEffect(() => {\r\n    if (!isClient || !syncTabs) {\r\n      return;\r\n    }\r\n\r\n    const handleStorageChange = (event: StorageEvent) => {\r\n      if (event.key !== key) {\r\n        return;\r\n      }\r\n\r\n      if (event.newValue !== null) {\r\n        try {\r\n          setStoredValue(deserializerRef.current(event.newValue));\r\n        } catch {\r\n          // If parsing fails, reset to initial value\r\n          setStoredValue(resolveInitialValue(initialValueRef.current));\r\n        }\r\n      } else {\r\n        // Key was removed in another tab\r\n        setStoredValue(resolveInitialValue(initialValueRef.current));\r\n      }\r\n    };\r\n\r\n    window.addEventListener(\"storage\", handleStorageChange);\r\n    return () => window.removeEventListener(\"storage\", handleStorageChange);\r\n  }, [key, syncTabs, isClient]);\r\n\r\n  // Re-read value when key changes\r\n  useEffect(() => {\r\n    if (!isClient) {\r\n      return;\r\n    }\r\n\r\n    try {\r\n      const item = window.localStorage.getItem(key);\r\n      if (item !== null) {\r\n        setStoredValue(deserializerRef.current(item));\r\n      } else {\r\n        setStoredValue(resolveInitialValue(initialValueRef.current));\r\n      }\r\n    } catch {\r\n      setStoredValue(resolveInitialValue(initialValueRef.current));\r\n    }\r\n    // eslint-disable-next-line react-hooks/exhaustive-deps\r\n  }, [key]);\r\n\r\n  return [storedValue, setValue, removeValue] as const;\r\n}\r\n"],"mappings":"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","names":[]}

package/dist/index.mjs

@@ -0,0 +1,109 @@
+// src/useLocalStorage.ts
+import { useCallback, useEffect, useRef, useState } from "react";
+function resolveInitialValue(initialValue) {
+  return typeof initialValue === "function" ? initialValue() : initialValue;
+}
+function useLocalStorage(key, initialValue, options = {}) {
+  const {
+    serializer = JSON.stringify,
+    deserializer = JSON.parse,
+    syncTabs = true,
+    onError
+  } = options;
+  const serializerRef = useRef(serializer);
+  const deserializerRef = useRef(deserializer);
+  const onErrorRef = useRef(onError);
+  serializerRef.current = serializer;
+  deserializerRef.current = deserializer;
+  onErrorRef.current = onError;
+  const initialValueRef = useRef(initialValue);
+  initialValueRef.current = initialValue;
+  const isClient = typeof window !== "undefined";
+  const [storedValue, setStoredValue] = useState(() => {
+    if (!isClient) {
+      return resolveInitialValue(initialValue);
+    }
+    try {
+      const item = window.localStorage.getItem(key);
+      if (item !== null) {
+        return deserializerRef.current(item);
+      }
+      return resolveInitialValue(initialValue);
+    } catch (error) {
+      onErrorRef.current?.(error);
+      return resolveInitialValue(initialValue);
+    }
+  });
+  const storedValueRef = useRef(storedValue);
+  storedValueRef.current = storedValue;
+  const setValue = useCallback(
+    (value) => {
+      try {
+        const currentValue = storedValueRef.current;
+        const valueToStore = value instanceof Function ? value(currentValue) : value;
+        setStoredValue(valueToStore);
+        if (typeof window !== "undefined") {
+          window.localStorage.setItem(
+            key,
+            serializerRef.current(valueToStore)
+          );
+        }
+      } catch (error) {
+        onErrorRef.current?.(error);
+      }
+    },
+    [key]
+  );
+  const removeValue = useCallback(() => {
+    try {
+      const initial = resolveInitialValue(initialValueRef.current);
+      setStoredValue(initial);
+      if (typeof window !== "undefined") {
+        window.localStorage.removeItem(key);
+      }
+    } catch (error) {
+      onErrorRef.current?.(error);
+    }
+  }, [key]);
+  useEffect(() => {
+    if (!isClient || !syncTabs) {
+      return;
+    }
+    const handleStorageChange = (event) => {
+      if (event.key !== key) {
+        return;
+      }
+      if (event.newValue !== null) {
+        try {
+          setStoredValue(deserializerRef.current(event.newValue));
+        } catch {
+          setStoredValue(resolveInitialValue(initialValueRef.current));
+        }
+      } else {
+        setStoredValue(resolveInitialValue(initialValueRef.current));
+      }
+    };
+    window.addEventListener("storage", handleStorageChange);
+    return () => window.removeEventListener("storage", handleStorageChange);
+  }, [key, syncTabs, isClient]);
+  useEffect(() => {
+    if (!isClient) {
+      return;
+    }
+    try {
+      const item = window.localStorage.getItem(key);
+      if (item !== null) {
+        setStoredValue(deserializerRef.current(item));
+      } else {
+        setStoredValue(resolveInitialValue(initialValueRef.current));
+      }
+    } catch {
+      setStoredValue(resolveInitialValue(initialValueRef.current));
+    }
+  }, [key]);
+  return [storedValue, setValue, removeValue];
+}
+export {
+  useLocalStorage
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/useLocalStorage.ts"],"sourcesContent":["import { useCallback, useEffect, useRef, useState } from \"react\";\r\n\r\n/**\r\n * Type for initial value that can be a value or a function returning a value (lazy initialization)\r\n */\r\nexport type InitialValue<T> = T | (() => T);\r\n\r\n/**\r\n * Options for useLocalStorage hook\r\n */\r\nexport interface UseLocalStorageOptions<T> {\r\n  /**\r\n   * Custom serializer function for converting value to string\r\n   * @default JSON.stringify\r\n   */\r\n  serializer?: (value: T) => string;\r\n  /**\r\n   * Custom deserializer function for parsing stored string to value\r\n   * @default JSON.parse\r\n   */\r\n  deserializer?: (value: string) => T;\r\n  /**\r\n   * Whether to sync value across browser tabs via storage event\r\n   * @default true\r\n   */\r\n  syncTabs?: boolean;\r\n  /**\r\n   * Callback function called when an error occurs\r\n   */\r\n  onError?: (error: Error) => void;\r\n}\r\n\r\n/**\r\n * Return type for useLocalStorage hook - tuple similar to useState\r\n */\r\nexport type UseLocalStorageReturn<T> = readonly [\r\n  /** Current stored value */\r\n  T,\r\n  /** Function to update the value (same signature as useState setter) */\r\n  React.Dispatch<React.SetStateAction<T>>,\r\n  /** Function to remove the value from localStorage */\r\n  () => void\r\n];\r\n\r\n/**\r\n * Helper function to resolve initial value (supports lazy initialization)\r\n */\r\nfunction resolveInitialValue<T>(initialValue: InitialValue<T>): T {\r\n  return typeof initialValue === \"function\"\r\n    ? (initialValue as () => T)()\r\n    : initialValue;\r\n}\r\n\r\n/**\r\n * A hook for persisting state in localStorage with automatic synchronization.\r\n * Works like useState but persists the value in localStorage.\r\n *\r\n * @template T - The type of the stored value\r\n * @param key - The localStorage key to store the value under\r\n * @param initialValue - Initial value or function returning initial value (lazy initialization)\r\n * @param options - Configuration options for serialization, sync, and error handling\r\n * @returns A tuple of [storedValue, setValue, removeValue]\r\n *\r\n * @example\r\n * ```tsx\r\n * // Basic usage with string\r\n * function ThemeToggle() {\r\n *   const [theme, setTheme, removeTheme] = useLocalStorage('theme', 'light');\r\n *\r\n *   return (\r\n *     <div>\r\n *       <p>Current theme: {theme}</p>\r\n *       <button onClick={() => setTheme('dark')}>Dark</button>\r\n *       <button onClick={() => setTheme('light')}>Light</button>\r\n *       <button onClick={removeTheme}>Reset</button>\r\n *     </div>\r\n *   );\r\n * }\r\n * ```\r\n *\r\n * @example\r\n * ```tsx\r\n * // With object type\r\n * interface UserSettings {\r\n *   notifications: boolean;\r\n *   language: string;\r\n * }\r\n *\r\n * const [settings, setSettings] = useLocalStorage<UserSettings>('settings', {\r\n *   notifications: true,\r\n *   language: 'en',\r\n * });\r\n *\r\n * // Functional update\r\n * setSettings(prev => ({ ...prev, notifications: false }));\r\n * ```\r\n *\r\n * @example\r\n * ```tsx\r\n * // With lazy initialization\r\n * const [config, setConfig] = useLocalStorage('config', () => computeExpensiveDefault());\r\n * ```\r\n *\r\n * @example\r\n * ```tsx\r\n * // With custom serializer/deserializer\r\n * const [date, setDate] = useLocalStorage<Date>('lastVisit', new Date(), {\r\n *   serializer: (d) => d.toISOString(),\r\n *   deserializer: (s) => new Date(s),\r\n * });\r\n * ```\r\n *\r\n * @example\r\n * ```tsx\r\n * // With error handling\r\n * const [value, setValue] = useLocalStorage('key', 'default', {\r\n *   onError: (error) => console.error('Storage error:', error),\r\n * });\r\n * ```\r\n */\r\nexport function useLocalStorage<T>(\r\n  key: string,\r\n  initialValue: InitialValue<T>,\r\n  options: UseLocalStorageOptions<T> = {}\r\n): UseLocalStorageReturn<T> {\r\n  const {\r\n    serializer = JSON.stringify,\r\n    deserializer = JSON.parse,\r\n    syncTabs = true,\r\n    onError,\r\n  } = options;\r\n\r\n  // Store options in refs for stable references and access to latest values\r\n  const serializerRef = useRef(serializer);\r\n  const deserializerRef = useRef(deserializer);\r\n  const onErrorRef = useRef(onError);\r\n  serializerRef.current = serializer;\r\n  deserializerRef.current = deserializer;\r\n  onErrorRef.current = onError;\r\n\r\n  // Store initialValue in ref for use in removeValue and storage event handler\r\n  const initialValueRef = useRef(initialValue);\r\n  initialValueRef.current = initialValue;\r\n\r\n  // SSR check - check once at module level for consistency\r\n  const isClient = typeof window !== \"undefined\";\r\n\r\n  // Lazy initialization with localStorage read\r\n  const [storedValue, setStoredValue] = useState<T>(() => {\r\n    if (!isClient) {\r\n      return resolveInitialValue(initialValue);\r\n    }\r\n\r\n    try {\r\n      const item = window.localStorage.getItem(key);\r\n      if (item !== null) {\r\n        return deserializerRef.current(item);\r\n      }\r\n      return resolveInitialValue(initialValue);\r\n    } catch (error) {\r\n      onErrorRef.current?.(error as Error);\r\n      return resolveInitialValue(initialValue);\r\n    }\r\n  });\r\n\r\n  // Store current value in ref for stable setValue reference\r\n  const storedValueRef = useRef<T>(storedValue);\r\n  storedValueRef.current = storedValue;\r\n\r\n  // setValue - stable reference (only depends on key)\r\n  const setValue = useCallback<React.Dispatch<React.SetStateAction<T>>>(\r\n    (value) => {\r\n      try {\r\n        const currentValue = storedValueRef.current;\r\n        const valueToStore =\r\n          value instanceof Function ? value(currentValue) : value;\r\n\r\n        setStoredValue(valueToStore);\r\n\r\n        if (typeof window !== \"undefined\") {\r\n          window.localStorage.setItem(\r\n            key,\r\n            serializerRef.current(valueToStore)\r\n          );\r\n        }\r\n      } catch (error) {\r\n        onErrorRef.current?.(error as Error);\r\n      }\r\n    },\r\n    [key]\r\n  );\r\n\r\n  // removeValue - stable reference\r\n  const removeValue = useCallback(() => {\r\n    try {\r\n      const initial = resolveInitialValue(initialValueRef.current);\r\n      setStoredValue(initial);\r\n\r\n      if (typeof window !== \"undefined\") {\r\n        window.localStorage.removeItem(key);\r\n      }\r\n    } catch (error) {\r\n      onErrorRef.current?.(error as Error);\r\n    }\r\n  }, [key]);\r\n\r\n  // Cross-tab synchronization via storage event\r\n  useEffect(() => {\r\n    if (!isClient || !syncTabs) {\r\n      return;\r\n    }\r\n\r\n    const handleStorageChange = (event: StorageEvent) => {\r\n      if (event.key !== key) {\r\n        return;\r\n      }\r\n\r\n      if (event.newValue !== null) {\r\n        try {\r\n          setStoredValue(deserializerRef.current(event.newValue));\r\n        } catch {\r\n          // If parsing fails, reset to initial value\r\n          setStoredValue(resolveInitialValue(initialValueRef.current));\r\n        }\r\n      } else {\r\n        // Key was removed in another tab\r\n        setStoredValue(resolveInitialValue(initialValueRef.current));\r\n      }\r\n    };\r\n\r\n    window.addEventListener(\"storage\", handleStorageChange);\r\n    return () => window.removeEventListener(\"storage\", handleStorageChange);\r\n  }, [key, syncTabs, isClient]);\r\n\r\n  // Re-read value when key changes\r\n  useEffect(() => {\r\n    if (!isClient) {\r\n      return;\r\n    }\r\n\r\n    try {\r\n      const item = window.localStorage.getItem(key);\r\n      if (item !== null) {\r\n        setStoredValue(deserializerRef.current(item));\r\n      } else {\r\n        setStoredValue(resolveInitialValue(initialValueRef.current));\r\n      }\r\n    } catch {\r\n      setStoredValue(resolveInitialValue(initialValueRef.current));\r\n    }\r\n    // eslint-disable-next-line react-hooks/exhaustive-deps\r\n  }, [key]);\r\n\r\n  return [storedValue, setValue, removeValue] as const;\r\n}\r\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@usefy/use-local-storage",
+  "version": "0.0.2",
+  "description": "A React hook for persisting state in localStorage with automatic synchronization",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.1",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^19.0.0",
+    "jsdom": "^27.3.0",
+    "react": "^19.0.0",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.16"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/geon0529/usefy.git",
+    "directory": "packages/use-local-storage"
+  },
+  "license": "MIT",
+  "keywords": [
+    "react",
+    "hooks",
+    "localStorage",
+    "storage",
+    "state",
+    "persistence"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist"
+  }
+}