Skip to content

⬅️ Back to Table of Contents

📄 useIDBKeyval

📊 Analysis Summary

Metric Count
🔧 Functions 6
📦 Imports 20
⚡ Async/Await Patterns 4
📐 Interfaces 3

📚 Table of Contents

🛠️ File Location:

📂 packages/integrations/useIDBKeyval/index.ts

📦 Imports

Name Source
ConfigurableWindow @vueuse/core
ConfigurableFlush @vueuse/shared
RemovableRef @vueuse/shared
ComputedRef vue
MaybeRefOrGetter vue
Ref vue
ShallowRef vue
defaultWindow @vueuse/core
tryOnScopeDispose @vueuse/core
useSupported @vueuse/core
watchPausable @vueuse/core
del idb-keyval
get idb-keyval
set idb-keyval
update idb-keyval
deepRef vue
nextTick vue
shallowRef vue
toRaw vue
toValue vue

Async/Await Patterns

Type Function Await Expressions Promise Chains
await-expression useIDBKeyval get(key), set(key, initValue), del(key), update(key, () => serializedValue... none
async-function read get(key), set(key, initValue) none
async-function write del(key), update(key, () => serializedValue) none
async-function setData write() none

Functions

useIDBKeyval(key: IDBValidKey, initialValue: MaybeRefOrGetter<T>, options: UseIDBOptions<T>): UseIDBKeyvalReturn<T>

Parameters:

  • key any: No description
  • initialValue any: No description
  • options any: No description
Raw JSDoc 
/**
 *
 * @param key
 * @param initialValue
 * @param options
 */

Calls:

  • console.error
  • useSupported (from @vueuse/core)
  • shallowRef (from vue)
  • complex_call_2121
  • toValue (from vue)
  • get (from idb-keyval)
  • serializer.write
  • set (from idb-keyval)
  • serializer.read
  • onError
  • read
  • del (from idb-keyval)
  • channel?.postMessage
  • toRaw (from vue)
  • update (from idb-keyval)
  • watchPausable (from @vueuse/core)
  • write
  • JSON.stringify
  • tryOnScopeDispose (from @vueuse/core)
  • channel?.close
  • channel.addEventListener
  • pauseWatch
  • nextTick (from vue)
  • resumeWatch
Code 
export function useIDBKeyval<T>(
  key: IDBValidKey,
  initialValue: MaybeRefOrGetter<T>,
  options: UseIDBOptions<T> = {},
): UseIDBKeyvalReturn<T> {
  const {
    flush = 'pre',
    deep = true,
    shallow = false,
    onError = (e) => {
      console.error(e)
    },
    writeDefaults = true,
    listenToStorageChanges = true,
    window = defaultWindow,
    serializer = {
      read: (raw: unknown) => raw as T,
      write: (value: T) => value,
    },
  } = options

  const isSupported = useSupported(() => window && 'BroadcastChannel' in window)

  const isFinished = shallowRef(false)
  const data = (shallow ? shallowRef : deepRef)(initialValue) as Ref<T>

  const rawInit: T = toValue(initialValue)

  async function read() {
    try {
      const rawValue = await get<T>(key)
      if (rawValue === undefined) {
        if (rawInit !== undefined && rawInit !== null && writeDefaults) {
          const initValue = serializer.write(rawInit)
          await set(key, initValue)
        }
      }
      else {
        data.value = serializer.read(rawValue)
      }
    }
    catch (e) {
      onError(e)
    }
    isFinished.value = true
  }

  read()

  let channel: BroadcastChannel | undefined

  async function write() {
    try {
      if (data.value == null) {
        await del(key)
        channel?.postMessage({ type: 'delete' })
      }
      else {
        const rawValue = toRaw(data.value)
        const serializedValue = serializer.write(rawValue)
        await update(key, () => serializedValue)
        channel?.postMessage({ type: 'set', value: serializedValue })
      }
    }
    catch (e) {
      onError(e)
    }
  }

  const {
    pause: pauseWatch,
    resume: resumeWatch,
  } = watchPausable(data, () => write(), { flush, deep })

  if (listenToStorageChanges && isSupported.value) {
    channel = new BroadcastChannel(`vueuse-idb-${JSON.stringify(key)}`)
    tryOnScopeDispose(() => channel?.close())

    channel.addEventListener('message', (event: MessageEvent) => {
      const { type, value } = event.data ?? {}
      pauseWatch()
      try {
        if (type === 'delete')
          data.value = rawInit
        else if (type === 'set')
          data.value = serializer.read(value)
      }
      catch (e) {
        onError(e)
      }
      finally {
        nextTick(resumeWatch)
      }
    })
  }

  async function setData(value: T): Promise<void> {
    pauseWatch()
    data.value = value
    await write()
    resumeWatch()
  }

  return {
    set: setData,
    isFinished,
    isSupported,
    data: data as RemovableRef<T>,
  }
}

Internal helpers

Declared inside another function in this file.

useIDBKeyval.read(raw: unknown): T

Parameters:

  • raw unknown

Returns: T

Code 
(raw: unknown) => raw as T

useIDBKeyval.write(value: T): T

Parameters:

  • value T

Returns: T

Code 
(value: T) => value

useIDBKeyval.read(): Promise<void>

Returns: Promise<void>

Calls:

  • get (from idb-keyval)
  • serializer.write
  • set (from idb-keyval)
  • serializer.read
  • onError
Code 
async function read() {
    try {
      const rawValue = await get<T>(key)
      if (rawValue === undefined) {
        if (rawInit !== undefined && rawInit !== null && writeDefaults) {
          const initValue = serializer.write(rawInit)
          await set(key, initValue)
        }
      }
      else {
        data.value = serializer.read(rawValue)
      }
    }
    catch (e) {
      onError(e)
    }
    isFinished.value = true
  }

useIDBKeyval.write(): Promise<void>

Returns: Promise<void>

Calls:

  • del (from idb-keyval)
  • channel?.postMessage
  • toRaw (from vue)
  • serializer.write
  • update (from idb-keyval)
  • onError
Code 
async function write() {
    try {
      if (data.value == null) {
        await del(key)
        channel?.postMessage({ type: 'delete' })
      }
      else {
        const rawValue = toRaw(data.value)
        const serializedValue = serializer.write(rawValue)
        await update(key, () => serializedValue)
        channel?.postMessage({ type: 'set', value: serializedValue })
      }
    }
    catch (e) {
      onError(e)
    }
  }

setData(value: T): Promise<void>

Parameters:

  • value T

Returns: Promise<void>

Calls:

  • pauseWatch
  • write
  • resumeWatch
Code 
async function setData(value: T): Promise<void> {
    pauseWatch()
    data.value = value
    await write()
    resumeWatch()
  }

Interfaces

Serializer<T>

Interface Code 
interface Serializer<T> {
  read: (raw: unknown) => T
  write: (value: T) => unknown
}

Properties

Name Type Optional Description
read (raw: unknown) => T ✗ not shown
write (value: T) => unknown ✗ not shown

UseIDBOptions<T>

Interface Code 
export interface UseIDBOptions<T> extends ConfigurableFlush, ConfigurableWindow {
  /**
   * Watch for deep changes
   *
   * @default true
   */
  deep?: boolean

  /**
   * On error callback
   *
   * Default log error to `console.error`
   */
  onError?: (error: unknown) => void

  /**
   * Use shallow ref as reference
   *
   * @default false
   */
  shallow?: boolean
  /**
   * Write the default value to the storage when it does not exist
   *
   * @default true
   */
  writeDefaults?: boolean

  /**
   * Custom data serialization
   */
  serializer?: Serializer<T>

  /**
   * Listen to storage changes from other tabs via BroadcastChannel,
   * useful for multiple tabs applications
   *
   * @default true
   */
  listenToStorageChanges?: boolean
}

Properties

Name Type Optional Description
deep boolean ✓ not shown
onError (error: unknown) => void ✓ not shown
shallow boolean ✓ not shown
writeDefaults boolean ✓ not shown
serializer Serializer<T> ✓ not shown
listenToStorageChanges boolean ✓ not shown

UseIDBKeyvalReturn<T>

Interface Code 
export interface UseIDBKeyvalReturn<T> {
  data: RemovableRef<T>
  isFinished: ShallowRef<boolean>
  isSupported: ComputedRef<boolean>
  set: (value: T) => Promise<void>
}

Properties

Name Type Optional Description
data RemovableRef<T> ✗ not shown
isFinished ShallowRef<boolean> ✗ not shown
isSupported ComputedRef<boolean> ✗ not shown
set (value: T) => Promise<void> ✗ not shown

Generated by Syntax Scribe