react-simplikit 0.0.29 → 0.0.31

package/dist/hooks/useDoubleClick/index.cjs

@@ -0,0 +1,75 @@
+"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/hooks/useDoubleClick/index.ts
+var useDoubleClick_exports = {};
+__export(useDoubleClick_exports, {
+  useDoubleClick: () => useDoubleClick
+});
+module.exports = __toCommonJS(useDoubleClick_exports);
+
+// src/hooks/useDoubleClick/useDoubleClick.ts
+var import_react2 = require("react");
+
+// src/hooks/usePreservedCallback/usePreservedCallback.ts
+var import_react = require("react");
+function usePreservedCallback(callback) {
+  const callbackRef = (0, import_react.useRef)(callback);
+  (0, import_react.useEffect)(() => {
+    callbackRef.current = callback;
+  }, [callback]);
+  return (0, import_react.useCallback)((...args) => {
+    return callbackRef.current(...args);
+  }, []);
+}
+
+// src/hooks/useDoubleClick/useDoubleClick.ts
+function useDoubleClick({
+  delay = 250,
+  click,
+  doubleClick
+}) {
+  const clickTimeout = (0, import_react2.useRef)(null);
+  const clearClickTimeout = usePreservedCallback(() => {
+    if (clickTimeout.current != null) {
+      window.clearTimeout(clickTimeout.current);
+      clickTimeout.current = null;
+    }
+  });
+  (0, import_react2.useEffect)(() => () => clearClickTimeout(), [clearClickTimeout]);
+  const handleEvent = (0, import_react2.useCallback)(
+    (event) => {
+      clearClickTimeout();
+      if (click && event.detail === 1) {
+        clickTimeout.current = window.setTimeout(() => {
+          click(event);
+        }, delay);
+      }
+      if (event.detail === 2) {
+        doubleClick(event);
+      }
+    },
+    [click, doubleClick, delay, clearClickTimeout]
+  );
+  return handleEvent;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useDoubleClick
+});

package/dist/hooks/useDoubleClick/index.d.cts

@@ -0,0 +1,42 @@
+import { MouseEvent } from 'react';
+
+type UseDoubleClickProps<E extends HTMLElement> = {
+    delay?: number;
+    click?: (event: MouseEvent<E>) => void;
+    doubleClick: (event: MouseEvent<E>) => void;
+};
+/**
+ * @description
+ * `useDoubleClick` is a React hook that differentiates between single and double click events.
+ * It delays the single click callback execution for a specified time, and cancels it if a second click (i.e. a double click) occurs within that time.
+ *
+ * @template {HTMLElement} E - The specific type of HTMLElement to be used with this hook (e.g., HTMLButtonElement, HTMLDivElement).
+ * @param {Object} params - Configuration options for click handling.
+ * @param {number} [params.delay=250] - The number of milliseconds to wait before triggering the single click callback. Defaults to 250ms.
+ * @param {(event: MouseEvent<E>) => void} [params.click] - The callback function to be executed on a single click.
+ * @param {(event: MouseEvent<E>) => void} params.doubleClick - The callback function to be executed on a double click. Required.
+ *
+ * @returns {(event: MouseEvent<E>) => void} A click handler function to attach to an element's `onClick` event.
+ *
+ * @example
+ * function GalleryCard() {
+ *   const [selected, setSelected] = useState(false);
+ *
+ *   const handleClick = () => setSelected((prev) => !prev);
+ *   const handleDoubleClick = () => alert('Zoom in!');
+ *
+ *   const handleEvent = useDoubleClick({
+ *     click: handleClick,
+ *     doubleClick: handleDoubleClick,
+ *   });
+ *
+ *   return (
+ *     <div onClick={handleEvent}>
+ *       {selected ? 'Selected' : 'Not selected'}
+ *     </div>
+ *   );
+ * }
+ */
+declare function useDoubleClick<E extends HTMLElement = HTMLElement>({ delay, click, doubleClick, }: UseDoubleClickProps<E>): (event: MouseEvent<E>) => void;
+
+export { useDoubleClick };

package/dist/hooks/useStorageState/index.cjs

@@ -114,18 +114,41 @@ var listeners = /* @__PURE__ */ new Set();
 var emitListeners = () => {
   listeners.forEach((listener) => listener());
 };
-function useStorageState(key, { storage = safeLocalStorage, defaultValue } = {}) {
+function isPlainObject(value) {
+  if (typeof value !== "object") {
+    return false;
+  }
+  const proto = Object.getPrototypeOf(value);
+  const hasObjectPrototype = proto === Object.prototype;
+  if (!hasObjectPrototype) {
+    return false;
+  }
+  return Object.prototype.toString.call(value) === "[object Object]";
+}
+var ensureSerializable = (value) => {
+  if (value[0] != null && !["string", "number", "boolean"].includes(typeof value[0]) && !(isPlainObject(value[0]) || Array.isArray(value[0]))) {
+    throw new Error("Received a non-serializable value");
+  }
+  return value;
+};
+function useStorageState(key, {
+  storage = safeLocalStorage,
+  defaultValue,
+  ...options
+} = {}) {
+  const serializedDefaultValue = defaultValue;
   const cache = (0, import_react.useRef)({
     data: null,
-    parsed: defaultValue
+    parsed: serializedDefaultValue
   });
   const getSnapshot = (0, import_react.useCallback)(() => {
+    const deserializer = "deserializer" in options ? options.deserializer : JSON.parse;
     const data = storage.get(key);
     if (data !== cache.current.data) {
       try {
-        cache.current.parsed = data != null ? JSON.parse(data) : defaultValue;
+        cache.current.parsed = data != null ? deserializer(data) : defaultValue;
       } catch {
-        cache.current.parsed = defaultValue;
+        cache.current.parsed = serializedDefaultValue;
       }
       cache.current.data = data;
     }
@@ -146,21 +169,25 @@ function useStorageState(key, { storage = safeLocalStorage, defaultValue } = {})
       };
     },
     () => getSnapshot(),
-    () => defaultValue
+    () => serializedDefaultValue
   );
   const setStorageState = (0, import_react.useCallback)(
     (value) => {
+      const serializer = "serializer" in options ? options.serializer : JSON.stringify;
       const nextValue = typeof value === "function" ? value(getSnapshot()) : value;
       if (nextValue == null) {
         storage.remove(key);
       } else {
-        storage.set(key, JSON.stringify(nextValue));
+        storage.set(key, serializer(nextValue));
       }
       emitListeners();
     },
     [getSnapshot, key, storage]
   );
-  return [storageState, setStorageState];
+  const refreshStorageState = (0, import_react.useCallback)(() => {
+    setStorageState(getSnapshot());
+  }, [storage, getSnapshot, setStorageState]);
+  return ensureSerializable([storageState, setStorageState, refreshStorageState]);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/hooks/useStorageState/index.d.cts

@@ -7,16 +7,20 @@ type Storage = {
     clear(): void;
 };
 
-type ToPrimitive<T> = T extends string ? string : T extends number ? number : T extends boolean ? boolean : never;
 type ToObject<T> = T extends unknown[] | Record<string, unknown> ? T : never;
-type Serializable<T> = T extends string | number | boolean ? ToPrimitive<T> : ToObject<T>;
+type Serializable<T> = T extends string | number | boolean ? T : ToObject<T>;
 type StorageStateOptions<T> = {
     storage?: Storage;
-    defaultValue?: Serializable<T>;
+    defaultValue?: T;
 };
 type StorageStateOptionsWithDefaultValue<T> = StorageStateOptions<T> & {
-    defaultValue: Serializable<T>;
+    defaultValue: T;
 };
+type StorageStateOptionsWithSerializer<T> = StorageStateOptions<T> & {
+    serializer: (value: Serializable<T>) => string;
+    deserializer: (value: string) => Serializable<T>;
+};
+type SerializableGuard<T extends readonly any[]> = T[0] extends any ? T : T[0] extends never ? 'Received a non-serializable value' : T;
 /**
  * @description
  * A React hook that functions like `useState` but persists the state value in browser storage.
@@ -26,11 +30,13 @@ type StorageStateOptionsWithDefaultValue<T> = StorageStateOptions<T> & {
  * @param {Object} [options] - Configuration options for storage behavior.
  * @param {Storage} [options.storage=localStorage] - The storage type (`localStorage` or `sessionStorage`). Defaults to `localStorage`.
  * @param {T} [options.defaultValue] - The initial value if no existing value is found.
+ * @param {Function} [options.serializer] - A function to serialize the state value to a string.
+ * @param {Function} [options.deserializer] - A function to deserialize the state value from a string.
  *
- * @returns {readonly [state: Serializable<T> | undefined, setState: (value: SetStateAction<Serializable<T> | undefined>) => void]} A tuple:
+ * @returns {readonly [state: Serializable<T> | undefined, setState: (value: SetStateAction<Serializable<T> | undefined>) => void, refreshState: () => void]} A tuple:
  * - state `Serializable<T> | undefined` - The current state value retrieved from storage;
  * - setState `(value: SetStateAction<Serializable<T> | undefined>) => void` - A function to update and persist the state;
- *
+ * - refreshState `() => void` - A function to refresh the state from storage;
  * @example
  * // Counter with persistent state
  * import { useStorageState } from 'react-simplikit';
@@ -43,8 +49,9 @@ type StorageStateOptionsWithDefaultValue<T> = StorageStateOptions<T> & {
  *   return <button onClick={() => setCount(prev => prev + 1)}>Count: {count}</button>;
  * }
  */
-declare function useStorageState<T>(key: string): readonly [Serializable<T> | undefined, (value: SetStateAction<Serializable<T> | undefined>) => void];
-declare function useStorageState<T>(key: string, { storage, defaultValue }: StorageStateOptionsWithDefaultValue<T>): readonly [Serializable<T>, (value: SetStateAction<Serializable<T>>) => void];
-declare function useStorageState<T>(key: string, { storage, defaultValue }: StorageStateOptions<T>): readonly [Serializable<T> | undefined, (value: SetStateAction<Serializable<T> | undefined>) => void];
+declare function useStorageState<T>(key: string): SerializableGuard<readonly [Serializable<T> | undefined, (value: SetStateAction<Serializable<T> | undefined>) => void, () => void]>;
+declare function useStorageState<T>(key: string, options: StorageStateOptionsWithDefaultValue<T>): SerializableGuard<readonly [Serializable<T>, (value: SetStateAction<Serializable<T>>) => void, () => void]>;
+declare function useStorageState<T>(key: string, options: StorageStateOptions<T>): SerializableGuard<readonly [Serializable<T> | undefined, (value: SetStateAction<Serializable<T> | undefined>) => void, () => void]>;
+declare function useStorageState<T>(key: string, options: StorageStateOptionsWithSerializer<T>): SerializableGuard<readonly [Serializable<T> | undefined, (value: SetStateAction<Serializable<T> | undefined>) => void, () => void]>;
 
 export { type Serializable, useStorageState };

package/dist/index.cjs

@@ -620,18 +620,41 @@ var listeners = /* @__PURE__ */ new Set();
 var emitListeners = () => {
   listeners.forEach((listener) => listener());
 };
-function useStorageState(key, { storage = safeLocalStorage, defaultValue } = {}) {
+function isPlainObject(value) {
+  if (typeof value !== "object") {
+    return false;
+  }
+  const proto = Object.getPrototypeOf(value);
+  const hasObjectPrototype = proto === Object.prototype;
+  if (!hasObjectPrototype) {
+    return false;
+  }
+  return Object.prototype.toString.call(value) === "[object Object]";
+}
+var ensureSerializable = (value) => {
+  if (value[0] != null && !["string", "number", "boolean"].includes(typeof value[0]) && !(isPlainObject(value[0]) || Array.isArray(value[0]))) {
+    throw new Error("Received a non-serializable value");
+  }
+  return value;
+};
+function useStorageState(key, {
+  storage = safeLocalStorage,
+  defaultValue,
+  ...options
+} = {}) {
+  const serializedDefaultValue = defaultValue;
   const cache = (0, import_react19.useRef)({
     data: null,
-    parsed: defaultValue
+    parsed: serializedDefaultValue
   });
   const getSnapshot = (0, import_react19.useCallback)(() => {
+    const deserializer = "deserializer" in options ? options.deserializer : JSON.parse;
     const data = storage.get(key);
     if (data !== cache.current.data) {
       try {
-        cache.current.parsed = data != null ? JSON.parse(data) : defaultValue;
+        cache.current.parsed = data != null ? deserializer(data) : defaultValue;
       } catch {
-        cache.current.parsed = defaultValue;
+        cache.current.parsed = serializedDefaultValue;
       }
       cache.current.data = data;
     }
@@ -652,21 +675,25 @@ function useStorageState(key, { storage = safeLocalStorage, defaultValue } = {})
       };
     },
     () => getSnapshot(),
-    () => defaultValue
+    () => serializedDefaultValue
   );
   const setStorageState = (0, import_react19.useCallback)(
     (value) => {
+      const serializer = "serializer" in options ? options.serializer : JSON.stringify;
       const nextValue = typeof value === "function" ? value(getSnapshot()) : value;
       if (nextValue == null) {
         storage.remove(key);
       } else {
-        storage.set(key, JSON.stringify(nextValue));
+        storage.set(key, serializer(nextValue));
       }
       emitListeners();
     },
     [getSnapshot, key, storage]
   );
-  return [storageState, setStorageState];
+  const refreshStorageState = (0, import_react19.useCallback)(() => {
+    setStorageState(getSnapshot());
+  }, [storage, getSnapshot, setStorageState]);
+  return ensureSerializable([storageState, setStorageState, refreshStorageState]);
 }
 
 // src/hooks/useThrottle/useThrottle.ts

package/esm/hooks/useDoubleClick/index.d.ts

@@ -0,0 +1,42 @@
+import { MouseEvent } from 'react';
+
+type UseDoubleClickProps<E extends HTMLElement> = {
+    delay?: number;
+    click?: (event: MouseEvent<E>) => void;
+    doubleClick: (event: MouseEvent<E>) => void;
+};
+/**
+ * @description
+ * `useDoubleClick` is a React hook that differentiates between single and double click events.
+ * It delays the single click callback execution for a specified time, and cancels it if a second click (i.e. a double click) occurs within that time.
+ *
+ * @template {HTMLElement} E - The specific type of HTMLElement to be used with this hook (e.g., HTMLButtonElement, HTMLDivElement).
+ * @param {Object} params - Configuration options for click handling.
+ * @param {number} [params.delay=250] - The number of milliseconds to wait before triggering the single click callback. Defaults to 250ms.
+ * @param {(event: MouseEvent<E>) => void} [params.click] - The callback function to be executed on a single click.
+ * @param {(event: MouseEvent<E>) => void} params.doubleClick - The callback function to be executed on a double click. Required.
+ *
+ * @returns {(event: MouseEvent<E>) => void} A click handler function to attach to an element's `onClick` event.
+ *
+ * @example
+ * function GalleryCard() {
+ *   const [selected, setSelected] = useState(false);
+ *
+ *   const handleClick = () => setSelected((prev) => !prev);
+ *   const handleDoubleClick = () => alert('Zoom in!');
+ *
+ *   const handleEvent = useDoubleClick({
+ *     click: handleClick,
+ *     doubleClick: handleDoubleClick,
+ *   });
+ *
+ *   return (
+ *     <div onClick={handleEvent}>
+ *       {selected ? 'Selected' : 'Not selected'}
+ *     </div>
+ *   );
+ * }
+ */
+declare function useDoubleClick<E extends HTMLElement = HTMLElement>({ delay, click, doubleClick, }: UseDoubleClickProps<E>): (event: MouseEvent<E>) => void;
+
+export { useDoubleClick };

package/esm/hooks/useDoubleClick/index.js

@@ -0,0 +1,48 @@
+// src/hooks/useDoubleClick/useDoubleClick.ts
+import { useCallback as useCallback2, useEffect as useEffect2, useRef as useRef2 } from "react";
+
+// src/hooks/usePreservedCallback/usePreservedCallback.ts
+import { useCallback, useEffect, useRef } from "react";
+function usePreservedCallback(callback) {
+  const callbackRef = useRef(callback);
+  useEffect(() => {
+    callbackRef.current = callback;
+  }, [callback]);
+  return useCallback((...args) => {
+    return callbackRef.current(...args);
+  }, []);
+}
+
+// src/hooks/useDoubleClick/useDoubleClick.ts
+function useDoubleClick({
+  delay = 250,
+  click,
+  doubleClick
+}) {
+  const clickTimeout = useRef2(null);
+  const clearClickTimeout = usePreservedCallback(() => {
+    if (clickTimeout.current != null) {
+      window.clearTimeout(clickTimeout.current);
+      clickTimeout.current = null;
+    }
+  });
+  useEffect2(() => () => clearClickTimeout(), [clearClickTimeout]);
+  const handleEvent = useCallback2(
+    (event) => {
+      clearClickTimeout();
+      if (click && event.detail === 1) {
+        clickTimeout.current = window.setTimeout(() => {
+          click(event);
+        }, delay);
+      }
+      if (event.detail === 2) {
+        doubleClick(event);
+      }
+    },
+    [click, doubleClick, delay, clearClickTimeout]
+  );
+  return handleEvent;
+}
+export {
+  useDoubleClick
+};

package/esm/hooks/useStorageState/index.d.ts

@@ -7,16 +7,20 @@ type Storage = {
     clear(): void;
 };
 
-type ToPrimitive<T> = T extends string ? string : T extends number ? number : T extends boolean ? boolean : never;
 type ToObject<T> = T extends unknown[] | Record<string, unknown> ? T : never;
-type Serializable<T> = T extends string | number | boolean ? ToPrimitive<T> : ToObject<T>;
+type Serializable<T> = T extends string | number | boolean ? T : ToObject<T>;
 type StorageStateOptions<T> = {
     storage?: Storage;
-    defaultValue?: Serializable<T>;
+    defaultValue?: T;
 };
 type StorageStateOptionsWithDefaultValue<T> = StorageStateOptions<T> & {
-    defaultValue: Serializable<T>;
+    defaultValue: T;
 };
+type StorageStateOptionsWithSerializer<T> = StorageStateOptions<T> & {
+    serializer: (value: Serializable<T>) => string;
+    deserializer: (value: string) => Serializable<T>;
+};
+type SerializableGuard<T extends readonly any[]> = T[0] extends any ? T : T[0] extends never ? 'Received a non-serializable value' : T;
 /**
  * @description
  * A React hook that functions like `useState` but persists the state value in browser storage.
@@ -26,11 +30,13 @@ type StorageStateOptionsWithDefaultValue<T> = StorageStateOptions<T> & {
  * @param {Object} [options] - Configuration options for storage behavior.
  * @param {Storage} [options.storage=localStorage] - The storage type (`localStorage` or `sessionStorage`). Defaults to `localStorage`.
  * @param {T} [options.defaultValue] - The initial value if no existing value is found.
+ * @param {Function} [options.serializer] - A function to serialize the state value to a string.
+ * @param {Function} [options.deserializer] - A function to deserialize the state value from a string.
  *
- * @returns {readonly [state: Serializable<T> | undefined, setState: (value: SetStateAction<Serializable<T> | undefined>) => void]} A tuple:
+ * @returns {readonly [state: Serializable<T> | undefined, setState: (value: SetStateAction<Serializable<T> | undefined>) => void, refreshState: () => void]} A tuple:
  * - state `Serializable<T> | undefined` - The current state value retrieved from storage;
  * - setState `(value: SetStateAction<Serializable<T> | undefined>) => void` - A function to update and persist the state;
- *
+ * - refreshState `() => void` - A function to refresh the state from storage;
  * @example
  * // Counter with persistent state
  * import { useStorageState } from 'react-simplikit';
@@ -43,8 +49,9 @@ type StorageStateOptionsWithDefaultValue<T> = StorageStateOptions<T> & {
  *   return <button onClick={() => setCount(prev => prev + 1)}>Count: {count}</button>;
  * }
  */
-declare function useStorageState<T>(key: string): readonly [Serializable<T> | undefined, (value: SetStateAction<Serializable<T> | undefined>) => void];
-declare function useStorageState<T>(key: string, { storage, defaultValue }: StorageStateOptionsWithDefaultValue<T>): readonly [Serializable<T>, (value: SetStateAction<Serializable<T>>) => void];
-declare function useStorageState<T>(key: string, { storage, defaultValue }: StorageStateOptions<T>): readonly [Serializable<T> | undefined, (value: SetStateAction<Serializable<T> | undefined>) => void];
+declare function useStorageState<T>(key: string): SerializableGuard<readonly [Serializable<T> | undefined, (value: SetStateAction<Serializable<T> | undefined>) => void, () => void]>;
+declare function useStorageState<T>(key: string, options: StorageStateOptionsWithDefaultValue<T>): SerializableGuard<readonly [Serializable<T>, (value: SetStateAction<Serializable<T>>) => void, () => void]>;
+declare function useStorageState<T>(key: string, options: StorageStateOptions<T>): SerializableGuard<readonly [Serializable<T> | undefined, (value: SetStateAction<Serializable<T> | undefined>) => void, () => void]>;
+declare function useStorageState<T>(key: string, options: StorageStateOptionsWithSerializer<T>): SerializableGuard<readonly [Serializable<T> | undefined, (value: SetStateAction<Serializable<T> | undefined>) => void, () => void]>;
 
 export { type Serializable, useStorageState };

package/esm/hooks/useStorageState/index.js

@@ -88,18 +88,41 @@ var listeners = /* @__PURE__ */ new Set();
 var emitListeners = () => {
   listeners.forEach((listener) => listener());
 };
-function useStorageState(key, { storage = safeLocalStorage, defaultValue } = {}) {
+function isPlainObject(value) {
+  if (typeof value !== "object") {
+    return false;
+  }
+  const proto = Object.getPrototypeOf(value);
+  const hasObjectPrototype = proto === Object.prototype;
+  if (!hasObjectPrototype) {
+    return false;
+  }
+  return Object.prototype.toString.call(value) === "[object Object]";
+}
+var ensureSerializable = (value) => {
+  if (value[0] != null && !["string", "number", "boolean"].includes(typeof value[0]) && !(isPlainObject(value[0]) || Array.isArray(value[0]))) {
+    throw new Error("Received a non-serializable value");
+  }
+  return value;
+};
+function useStorageState(key, {
+  storage = safeLocalStorage,
+  defaultValue,
+  ...options
+} = {}) {
+  const serializedDefaultValue = defaultValue;
   const cache = useRef({
     data: null,
-    parsed: defaultValue
+    parsed: serializedDefaultValue
   });
   const getSnapshot = useCallback(() => {
+    const deserializer = "deserializer" in options ? options.deserializer : JSON.parse;
     const data = storage.get(key);
     if (data !== cache.current.data) {
       try {
-        cache.current.parsed = data != null ? JSON.parse(data) : defaultValue;
+        cache.current.parsed = data != null ? deserializer(data) : defaultValue;
       } catch {
-        cache.current.parsed = defaultValue;
+        cache.current.parsed = serializedDefaultValue;
       }
       cache.current.data = data;
     }
@@ -120,21 +143,25 @@ function useStorageState(key, { storage = safeLocalStorage, defaultValue } = {})
       };
     },
     () => getSnapshot(),
-    () => defaultValue
+    () => serializedDefaultValue
   );
   const setStorageState = useCallback(
     (value) => {
+      const serializer = "serializer" in options ? options.serializer : JSON.stringify;
       const nextValue = typeof value === "function" ? value(getSnapshot()) : value;
       if (nextValue == null) {
         storage.remove(key);
       } else {
-        storage.set(key, JSON.stringify(nextValue));
+        storage.set(key, serializer(nextValue));
       }
       emitListeners();
     },
     [getSnapshot, key, storage]
   );
-  return [storageState, setStorageState];
+  const refreshStorageState = useCallback(() => {
+    setStorageState(getSnapshot());
+  }, [storage, getSnapshot, setStorageState]);
+  return ensureSerializable([storageState, setStorageState, refreshStorageState]);
 }
 export {
   useStorageState

package/esm/index.js

@@ -571,18 +571,41 @@ var listeners = /* @__PURE__ */ new Set();
 var emitListeners = () => {
   listeners.forEach((listener) => listener());
 };
-function useStorageState(key, { storage = safeLocalStorage, defaultValue } = {}) {
+function isPlainObject(value) {
+  if (typeof value !== "object") {
+    return false;
+  }
+  const proto = Object.getPrototypeOf(value);
+  const hasObjectPrototype = proto === Object.prototype;
+  if (!hasObjectPrototype) {
+    return false;
+  }
+  return Object.prototype.toString.call(value) === "[object Object]";
+}
+var ensureSerializable = (value) => {
+  if (value[0] != null && !["string", "number", "boolean"].includes(typeof value[0]) && !(isPlainObject(value[0]) || Array.isArray(value[0]))) {
+    throw new Error("Received a non-serializable value");
+  }
+  return value;
+};
+function useStorageState(key, {
+  storage = safeLocalStorage,
+  defaultValue,
+  ...options
+} = {}) {
+  const serializedDefaultValue = defaultValue;
   const cache = useRef10({
     data: null,
-    parsed: defaultValue
+    parsed: serializedDefaultValue
   });
   const getSnapshot = useCallback8(() => {
+    const deserializer = "deserializer" in options ? options.deserializer : JSON.parse;
     const data = storage.get(key);
     if (data !== cache.current.data) {
       try {
-        cache.current.parsed = data != null ? JSON.parse(data) : defaultValue;
+        cache.current.parsed = data != null ? deserializer(data) : defaultValue;
       } catch {
-        cache.current.parsed = defaultValue;
+        cache.current.parsed = serializedDefaultValue;
       }
       cache.current.data = data;
     }
@@ -603,21 +626,25 @@ function useStorageState(key, { storage = safeLocalStorage, defaultValue } = {})
       };
     },
     () => getSnapshot(),
-    () => defaultValue
+    () => serializedDefaultValue
   );
   const setStorageState = useCallback8(
     (value) => {
+      const serializer = "serializer" in options ? options.serializer : JSON.stringify;
       const nextValue = typeof value === "function" ? value(getSnapshot()) : value;
       if (nextValue == null) {
         storage.remove(key);
       } else {
-        storage.set(key, JSON.stringify(nextValue));
+        storage.set(key, serializer(nextValue));
       }
       emitListeners();
     },
     [getSnapshot, key, storage]
   );
-  return [storageState, setStorageState];
+  const refreshStorageState = useCallback8(() => {
+    setStorageState(getSnapshot());
+  }, [storage, getSnapshot, setStorageState]);
+  return ensureSerializable([storageState, setStorageState, refreshStorageState]);
 }
 
 // src/hooks/useThrottle/useThrottle.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-simplikit",
-  "version": "0.0.29",
+  "version": "0.0.31",
   "main": "./dist/index.cjs",
   "type": "module",
   "sideEffects": false,