react-simplikit 0.0.29 → 0.0.30

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/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.30",
   "main": "./dist/index.cjs",
   "type": "module",
   "sideEffects": false,