Merge branch 'main' into feat/add-use-counter

Author: JeongHwan-dev

package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-simplikit",
-  "version": "0.0.29",
+  "version": "0.0.30",
   "main": "./src/index.ts",
   "type": "module",
   "sideEffects": false,

src/hooks/useStorageState/useStorageState.spec.ts

@@ -190,6 +190,44 @@ describe('useStorageState', () => {
 
       expect(result2.current[0]).toBe('updated value');
     });
+
+    it('should refresh storage state', async () => {
+      const { result } = await renderHookSSR(() => useStorageState('test-key', { storage }));
+
+      storage.set('test-key', JSON.stringify({ hello: 'world' }));
+
+      act(() => {
+        result.current[2]();
+      });
+
+      expect(result.current[0]).toEqual({ hello: 'world' });
+    });
+
+    it('should work with custom serializer and deserializer', async () => {
+      const serializer = (value: any) =>
+        ['string', 'number', 'boolean'].includes(typeof value) ? value : JSON.stringify(value);
+      const deserializer = (value: any) =>
+        /^(\d+)|(true|false)|([^[].*)|([^{].*)$/.test(value) ? value : JSON.parse(value);
+
+      const { result } = await renderHookSSR(() => useStorageState('test-key', { storage, serializer, deserializer }));
+
+      act(() => {
+        result.current[1]('hello');
+      });
+
+      expect(result.current[0]).toEqual('hello');
+    });
+
+    it('should throw error when value is not serializable', async () => {
+      expect(
+        async () => await renderHookSSR(() => useStorageState('test-key', { storage, defaultValue: () => 'world' }))
+      ).rejects.toThrow('Received a non-serializable value');
+
+      expect(
+        async () =>
+          await renderHookSSR(() => useStorageState('test-key', { storage, defaultValue: new (class Cls {})() }))
+      ).rejects.toThrow('Received a non-serializable value');
+    });
   };
 
   describe('MemoStorage', () => {

src/hooks/useStorageState/useStorageState.ts

@@ -1,27 +1,66 @@
+/* eslint-disable react-hooks/exhaustive-deps */
 import { SetStateAction, useCallback, useRef, useSyncExternalStore } from 'react';
 
 import { safeLocalStorage, Storage } from './storage.ts';
 
-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;
 
-export type Serializable<T> = T extends string | number | boolean ? ToPrimitive<T> : ToObject<T>;
+export 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;
+
 const listeners = new Set<() => void>();
 
 const emitListeners = () => {
   listeners.forEach(listener => listener());
 };
 
+function isPlainObject(value: unknown): value is Record<PropertyKey, any> {
+  if (typeof value !== 'object') {
+    return false;
+  }
+
+  const proto = Object.getPrototypeOf(value) as typeof Object.prototype | null;
+
+  const hasObjectPrototype = proto === Object.prototype;
+
+  if (!hasObjectPrototype) {
+    return false;
+  }
+
+  return Object.prototype.toString.call(value) === '[object Object]';
+}
+
+const ensureSerializable = <T extends readonly any[]>(value: T): SerializableGuard<T> => {
+  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 as SerializableGuard<T>;
+};
+
 /**
  * @description
  * A React hook that functions like `useState` but persists the state value in browser storage.
@@ -31,11 +70,13 @@ const emitListeners = () => {
  * @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';
@@ -50,35 +91,53 @@ const emitListeners = () => {
  */
 export function useStorageState<T>(
   key: string
-): readonly [Serializable<T> | undefined, (value: SetStateAction<Serializable<T> | undefined>) => void];
+): SerializableGuard<
+  readonly [Serializable<T> | undefined, (value: SetStateAction<Serializable<T> | undefined>) => void, () => void]
+>;
 export function useStorageState<T>(
   key: string,
-  { storage, defaultValue }: StorageStateOptionsWithDefaultValue<T>
-): readonly [Serializable<T>, (value: SetStateAction<Serializable<T>>) => void];
+  options: StorageStateOptionsWithDefaultValue<T>
+): SerializableGuard<readonly [Serializable<T>, (value: SetStateAction<Serializable<T>>) => void, () => void]>;
 export function useStorageState<T>(
   key: string,
-  { storage, defaultValue }: StorageStateOptions<T>
-): readonly [Serializable<T> | undefined, (value: SetStateAction<Serializable<T> | undefined>) => void];
+  options: StorageStateOptions<T>
+): SerializableGuard<
+  readonly [Serializable<T> | undefined, (value: SetStateAction<Serializable<T> | undefined>) => void, () => void]
+>;
 export function useStorageState<T>(
   key: string,
-  { storage = safeLocalStorage, defaultValue }: StorageStateOptions<T> = {}
-): readonly [Serializable<T> | undefined, (value: SetStateAction<Serializable<T> | undefined>) => void] {
+  options: StorageStateOptionsWithSerializer<T>
+): SerializableGuard<
+  readonly [Serializable<T> | undefined, (value: SetStateAction<Serializable<T> | undefined>) => void, () => void]
+>;
+export function useStorageState<T>(
+  key: string,
+  {
+    storage = safeLocalStorage,
+    defaultValue,
+    ...options
+  }: StorageStateOptions<T> | StorageStateOptionsWithSerializer<T> = {}
+): SerializableGuard<
+  readonly [Serializable<T> | undefined, (value: SetStateAction<Serializable<T> | undefined>) => void, () => void]
+> {
+  const serializedDefaultValue = defaultValue as Serializable<T>;
   const cache = useRef<{
     data: string | null;
     parsed: Serializable<T> | undefined;
   }>({
     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;
     }
@@ -104,22 +163,28 @@ export function useStorageState<T>(
       };
     },
     () => getSnapshot(),
-    () => defaultValue
+    () => serializedDefaultValue
   );
 
   const setStorageState = useCallback(
     (value: SetStateAction<Serializable<T> | undefined>) => {
+      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] as const;
+  const refreshStorageState = useCallback(() => {
+    setStorageState(getSnapshot());
+  }, [storage, getSnapshot, setStorageState]);
+
+  return ensureSerializable([storageState, setStorageState, refreshStorageState] as const);
 }

vitest.config.ts

@@ -13,7 +13,7 @@ export default defineConfig({
       reporter: ['text', 'json'],
       extension: ['.ts', '.tsx'],
       include: ['src/**/*.ts?(x)'],
-      exclude: ['src/**/index.ts', 'src/**/*.spec.ts?(x)'],
+      exclude: ['src/_internal', 'src/**/index.ts', 'src/**/*.spec.ts?(x)'],
     },
   },
 });