feat(useIDBKeyval): add options.serializer (#4781)

matthewjumpsoffbuildings · OrbisK · 43081j · web-flow · commit bb831783fd47 · 2025-07-09T13:55:36.000Z
Co-authored-by: Robin &lt;robin.kehl@singular-it.de&gt;
Co-authored-by: James Garbutt &lt;43081j@users.noreply.github.com&gt;
diff --git a/packages/integrations/useIDBKeyval/index.test.ts b/packages/integrations/useIDBKeyval/index.test.ts
@@ -1,19 +1,20 @@
+import type { Ref } from 'vue'
 import { get, set } from 'idb-keyval'
-import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { nextTick } from 'vue'
 import { useIDBKeyval } from './index'
 
-const cache = {} as any
+const cache = new Map<string, unknown>()
 
 vi.mock('idb-keyval', () => ({
-  get: (key: string) => Promise.resolve(cache[key]),
+  get: (key: string) => Promise.resolve(cache.get(key)),
   set: vi.fn((key: string, value: any) => new Promise((resolve, reject) => {
     if (value === 'error') {
       reject(new Error('set error'))
       return
     }
 
-    cache[key] = value
+    cache.set(key, value)
 
     resolve(undefined)
   })),
@@ -24,30 +25,39 @@ vi.mock('idb-keyval', () => ({
       return
     }
 
-    cache[key] = value
+    cache.set(key, value)
 
     resolve(undefined)
   }),
   del: (key: string) => {
-    delete cache[key]
+    cache.delete(key)
   },
 }))
 
 const KEY1 = 'vue-use-idb-keyval-1'
 const KEY2 = 'vue-use-idb-keyval-2'
 const KEY3 = 'vue-use-idb-keyval-3'
 const KEY4 = 'vue-use-idb-keyval-4'
+
 describe('useIDBKeyval', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
+  let data1: Ref<{ count: number } | null>
+  let data2: Ref<string[] | null>
+  let data3: Ref<string | null>
+
+  beforeEach(async () => {
     console.error = vi.fn()
-  })
 
-  set(KEY3, 'hello')
+    await set(KEY3, 'hello');
 
-  const { data: data1 } = useIDBKeyval(KEY1, { count: 0 })
-  const { data: data2 } = useIDBKeyval(KEY2, ['foo', 'bar'])
-  const { data: data3 } = useIDBKeyval(KEY3, 'world', { shallow: true })
+    ({ data: data1 } = useIDBKeyval(KEY1, { count: 0 }));
+    ({ data: data2 } = useIDBKeyval(KEY2, ['foo', 'bar']));
+    ({ data: data3 } = useIDBKeyval(KEY3, 'world', { shallow: true }))
+  })
+
+  afterEach(() => {
+    vi.clearAllMocks()
+    cache.clear()
+  })
 
   it('get/set', async () => {
     expect(data1.value).toEqual({ count: 0 })
@@ -60,8 +70,8 @@ describe('useIDBKeyval', () => {
   })
 
   it('update', async () => {
-    data1.value.count++
-    data2.value.push('woo')
+    data1.value!.count++
+    data2.value!.push('woo')
     data3.value = 'world'
 
     expect(await get(KEY1)).toEqual(data1.value)
@@ -109,6 +119,43 @@ describe('useIDBKeyval', () => {
   it('writeDefaults false', async () => {
     useIDBKeyval(KEY4, 'test', { writeDefaults: false })
 
-    expect(set).toHaveBeenCalledTimes(0)
+    // the initial 3 IDB calls minus this one
+    expect(set).toHaveBeenCalledTimes(3)
+  })
+  it('get/set with serializer', async () => {
+    const serializer = {
+      read(raw: unknown): string {
+        return raw === 1 ? 'foo' : 'bar'
+      },
+      write(value: string): unknown {
+        return value === 'foo' ? 1 : 0
+      },
+    }
+
+    const { data } = useIDBKeyval(KEY4, 'foo', { serializer })
+
+    await nextTick()
+
+    expect(data.value).toEqual('foo')
+    expect(await get(KEY4)).toEqual(1)
+  })
+  it('get/set with serializer and existing value', async () => {
+    const serializer = {
+      read(raw: unknown): string {
+        return raw === 1 ? 'foo' : 'bar'
+      },
+      write(value: string): unknown {
+        return value === 'foo' ? 1 : 0
+      },
+    }
+
+    await set(KEY4, 0)
+
+    const { data } = useIDBKeyval(KEY4, 'foo', { serializer })
+
+    await nextTick()
+
+    expect(data.value).toEqual('bar')
+    expect(await get(KEY4)).toEqual(0)
   })
 })
diff --git a/packages/integrations/useIDBKeyval/index.ts b/packages/integrations/useIDBKeyval/index.ts
@@ -4,7 +4,12 @@ import { watchPausable } from '@vueuse/core'
 import { del, get, set, update } from 'idb-keyval'
 import { ref as deepRef, shallowRef, toRaw, toValue } from 'vue'
 
-export interface UseIDBOptions extends ConfigurableFlush {
+interface Serializer<T> {
+  read: (raw: unknown) => T
+  write: (value: T) => unknown
+}
+
+export interface UseIDBOptions<T> extends ConfigurableFlush {
   /**
    * Watch for deep changes
    *
@@ -31,6 +36,11 @@ export interface UseIDBOptions extends ConfigurableFlush {
    * @default true
    */
   writeDefaults?: boolean
+
+  /**
+   * Custom data serialization
+   */
+  serializer?: Serializer<T>
 }
 
 export interface UseIDBKeyvalReturn<T> {
@@ -48,7 +58,7 @@ export interface UseIDBKeyvalReturn<T> {
 export function useIDBKeyval<T>(
   key: IDBValidKey,
   initialValue: MaybeRefOrGetter<T>,
-  options: UseIDBOptions = {},
+  options: UseIDBOptions<T> = {},
 ): UseIDBKeyvalReturn<T> {
   const {
     flush = 'pre',
@@ -58,6 +68,10 @@ export function useIDBKeyval<T>(
       console.error(e)
     },
     writeDefaults = true,
+    serializer = {
+      read: (raw: unknown) => raw as T,
+      write: (value: T) => value,
+    },
   } = options
 
   const isFinished = shallowRef(false)
@@ -69,11 +83,13 @@ export function useIDBKeyval<T>(
     try {
       const rawValue = await get<T>(key)
       if (rawValue === undefined) {
-        if (rawInit !== undefined && rawInit !== null && writeDefaults)
-          await set(key, rawInit)
+        if (rawInit !== undefined && rawInit !== null && writeDefaults) {
+          const initValue = serializer.write(rawInit)
+          await set(key, initValue)
+        }
       }
       else {
-        data.value = rawValue
+        data.value = serializer.read(rawValue)
       }
     }
     catch (e) {
@@ -90,8 +106,9 @@ export function useIDBKeyval<T>(
         await del(key)
       }
       else {
-        // IndexedDB does not support saving proxies, convert from proxy before saving
-        await update(key, () => toRaw(data.value))
+        const rawValue = toRaw(data.value)
+        const serializedValue = serializer.write(rawValue)
+        await update(key, () => serializedValue)
       }
     }
     catch (e) {
