@xiao-ying/miniapp-hooks 1.1.0

package/src/use-storage.ts

@@ -0,0 +1,170 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+/**
+ * useStorage 的配置项。
+ *
+ * @param defaultValue - 初始值（当 storage 为空时使用）。
+ * @param disabled - 禁用读写与订阅。
+ */
+export interface UseStorageOptions<T> {
+  defaultValue?: T
+  disabled?: boolean
+}
+
+/**
+ * useStorage 的返回结果。
+ *
+ * - `value`: 当前值
+ * - `loading`: 是否在加载
+ * - `error`: 最近一次错误
+ * - `setValue/remove/refresh`: 操作方法
+ */
+export interface UseStorageResult<T> {
+  value: T | null
+  loading: boolean
+  error?: unknown
+  setValue: (next: T) => Promise<void>
+  remove: () => Promise<void>
+  refresh: () => Promise<void>
+}
+
+/**
+ * 读取并订阅小应小程序存储的指定 key。
+ *
+ * @param key - storage key。
+ * @param options - 读取配置。
+ *
+ * @example
+ * const storage = useStorage<string>('nickname', { defaultValue: '游客' })
+ */
+export const useStorage = <T = any>(
+  key: string,
+  options: UseStorageOptions<T> = {}
+): UseStorageResult<T> => {
+  const { defaultValue, disabled = false } = options
+  const initialDefault = (defaultValue as T | null | undefined) ?? null
+  const isMounted = useRef(true)
+
+  const [value, setValueState] = useState<T | null>(initialDefault)
+  const [loading, setLoading] = useState<boolean>(!disabled)
+  const [error, setError] = useState<unknown>()
+
+  useEffect(() => {
+    isMounted.current = true
+    return () => {
+      isMounted.current = false
+    }
+  }, [])
+
+  const setValueSafe = useCallback((next: T | null) => {
+    if (!isMounted.current) return
+    setValueState(next)
+  }, [])
+
+  const setLoadingSafe = useCallback((next: boolean) => {
+    if (!isMounted.current) return
+    setLoading(next)
+  }, [])
+
+  const setErrorSafe = useCallback((next?: unknown) => {
+    if (!isMounted.current) return
+    setError(next)
+  }, [])
+
+  const refresh = useCallback(async (): Promise<void> => {
+    if (disabled) {
+      setValueSafe(initialDefault)
+      setLoadingSafe(false)
+      setErrorSafe(undefined)
+      return
+    }
+
+    setLoadingSafe(true)
+    try {
+      const res = await xy.getStorage<T>({ key })
+      const resolved =
+        res?.data === null || typeof res?.data === 'undefined' ? initialDefault : res.data
+      setValueSafe(resolved as T | null)
+      setErrorSafe(undefined)
+    } catch (err) {
+      setErrorSafe(err)
+      throw err
+    } finally {
+      setLoadingSafe(false)
+    }
+  }, [disabled, initialDefault, key, setErrorSafe, setLoadingSafe, setValueSafe, xy])
+
+  useEffect(() => {
+    void refresh()
+  }, [refresh])
+
+  useEffect(() => {
+    if (disabled || typeof xy.onStorageChange !== 'function') {
+      return
+    }
+
+    const unsubscribe = xy.onStorageChange((event) => {
+      if (!event) return
+      if (event.key === '*' || event.key === key) {
+        const nextValue =
+          event.key === '*' ? initialDefault : ((event.newValue ?? initialDefault) as T | null)
+        setValueSafe(nextValue)
+        setErrorSafe(undefined)
+      }
+    })
+
+    return () => {
+      if (typeof unsubscribe === 'function') {
+        unsubscribe()
+      }
+    }
+  }, [disabled, initialDefault, key, setErrorSafe, setValueSafe, xy])
+
+  const setValue = useCallback(
+    async (next: T): Promise<void> => {
+      if (disabled) return
+      setLoadingSafe(true)
+      try {
+        const res = await xy.setStorage({ key, data: next })
+        if (res?.success === false) {
+          throw new Error('SET_STORAGE_FAILED')
+        }
+        setValueSafe(next)
+        setErrorSafe(undefined)
+      } catch (err) {
+        setErrorSafe(err)
+        throw err
+      } finally {
+        setLoadingSafe(false)
+      }
+    },
+    [disabled, key, setErrorSafe, setLoadingSafe, setValueSafe, xy]
+  )
+
+  const remove = useCallback(async (): Promise<void> => {
+    if (disabled) return
+    setLoadingSafe(true)
+    try {
+      const res = await xy.removeStorage({ key })
+      if (res?.success === false) {
+        throw new Error('REMOVE_STORAGE_FAILED')
+      }
+      setValueSafe(initialDefault)
+      setErrorSafe(undefined)
+    } catch (err) {
+      setErrorSafe(err)
+      throw err
+    } finally {
+      setLoadingSafe(false)
+    }
+  }, [disabled, initialDefault, key, setErrorSafe, setLoadingSafe, setValueSafe, xy])
+
+  return {
+    value,
+    loading,
+    error,
+    setValue,
+    remove,
+    refresh
+  }
+}