feat(useStorageAsync): add onReady option and Promise return (#4158)

asika32764 · ferferga · OrbisK · web-flow · commit 3a2df2e18c41 · 2025-07-28T04:45:58.000Z
Co-authored-by: Fernando Fernández &lt;ferferga@hotmail.com&gt;
Co-authored-by: Robin &lt;robin.kehl@singular-it.de&gt;
Co-authored-by: autofix-ci[bot] &lt;114827586+autofix-ci[bot]@users.noreply.github.com&gt;
Co-authored-by: Anthony Fu &lt;anthonyfu117@hotmail.com&gt;
diff --git a/packages/core/useStorageAsync/index.md b/packages/core/useStorageAsync/index.md
@@ -8,4 +8,81 @@ Reactive Storage in with async support.
 
 ## Usage
 
-Please refer to `useStorage`.
+The basic usage please refer to `useStorage`.
+
+## Wait First Loaded
+
+When user entering your app, `useStorageAsync()` will start loading value from an async storage,
+sometimes you may get the default initial value, not the real value stored in storage at the very
+beginning.
+
+```ts
+import { useStorageAsync } from '@vueuse/core'
+
+const accessToken = useStorageAsync('access.token', '', SomeAsyncStorage)
+
+// accessToken.value may be empty before the async storage is ready
+console.log(accessToken.value) // ""
+
+setTimeout(() => {
+  // After some time, the async storage is ready
+  console.log(accessToken.value) // "the real value stored in storage"
+}, 500)
+```
+
+In this case, you can wait the storage prepared, the returned value is also a `Promise`,
+so you can wait it resolved in your template or script.
+
+```ts
+// Use top-level await if your environment supports it
+const accessToken = await useStorageAsync('access.token', '', SomeAsyncStorage)
+
+console.log(accessToken.value) // "the real value stored in storage"
+```
+
+If you must wait multiple storages, put them into a `Promise.allSettled()`
+
+```ts
+router.onReady(async () => {
+  await Promise.allSettled([
+    accessToken,
+    refreshToken,
+    userData,
+  ])
+
+  app.mount('app')
+})
+```
+
+There is a callback named `onReady` in options:
+
+```ts
+import { useStorageAsync } from '@vueuse/core'
+
+// Use ES2024 Promise.withResolvers, you may use any Deferred object or EventBus to do same thing.
+const { promise, resolve } = Promise.withResolvers()
+
+const accessToken = useStorageAsync('access.token', '', SomeAsyncStorage, {
+  onReady(value) {
+    resolve(value)
+  }
+})
+
+// At main.ts
+router.onReady(async () => {
+  // Let's wait accessToken loaded
+  await promise
+
+  // Now accessToken has loaded, we can safely mount our app
+
+  app.mount('app')
+})
+```
+
+Simply use `resolve` as callback:
+
+```ts
+const accessToken = useStorageAsync('access.token', '', SomeAsyncStorage, {
+  onReady: resolve
+})
+```
diff --git a/packages/core/useStorageAsync/index.test.ts b/packages/core/useStorageAsync/index.test.ts
@@ -0,0 +1,81 @@
+import type { Awaitable, StorageLikeAsync } from '@vueuse/core'
+import { createEventHook, useStorageAsync } from '@vueuse/core'
+import { beforeEach, describe, expect, it } from 'vitest'
+
+const KEY = 'custom-key'
+const KEY2 = 'custom-key2'
+const asyncDelay = 10
+const localStorage = globalThis.localStorage
+
+class AsyncStubStorage implements StorageLikeAsync {
+  getItem(key: string): Awaitable<string | null> {
+    return new Promise((resolve) => {
+      setTimeout(() => {
+        resolve(localStorage.getItem(key))
+      }, asyncDelay)
+    })
+  }
+
+  removeItem(key: string): Awaitable<void> {
+    return new Promise((resolve) => {
+      setTimeout(() => {
+        localStorage.removeItem(key)
+        resolve()
+      }, asyncDelay)
+    })
+  }
+
+  setItem(key: string, value: string): Awaitable<void> {
+    return new Promise((resolve) => {
+      setTimeout(() => {
+        localStorage.setItem(key, value)
+        resolve()
+      }, asyncDelay)
+    })
+  }
+}
+
+describe('useStorageAsync', () => {
+  beforeEach(() => {
+    localStorage.clear()
+  })
+
+  it('onReady', async () => {
+    localStorage.setItem(KEY, 'CurrentValue')
+
+    const loaded = createEventHook()
+    const promise = new Promise<string>((resolve) => {
+      loaded.on(resolve)
+    })
+
+    const storage = useStorageAsync(
+      KEY,
+      '',
+      new AsyncStubStorage(),
+      {
+        onReady(value) {
+          loaded.trigger(value)
+        },
+      },
+    )
+
+    expect(storage.value).toBe('')
+    await expect(promise).resolves.toBe('CurrentValue')
+  })
+
+  it('onReadyByPromise', async () => {
+    localStorage.setItem(KEY2, 'AnotherValue')
+
+    const storage = useStorageAsync(
+      KEY2,
+      '',
+      new AsyncStubStorage(),
+    )
+
+    expect(storage.value).toBe('')
+
+    storage.then((result) => {
+      expect(result.value).toBe('AnotherValue')
+    })
+  })
+})
diff --git a/packages/core/useStorageAsync/index.ts b/packages/core/useStorageAsync/index.ts
@@ -15,13 +15,18 @@ export interface UseStorageAsyncOptions<T> extends Omit<UseStorageOptions<T>, 's
    * Custom data serialization
    */
   serializer?: SerializerAsync<T>
+
+  /**
+   * On first value loaded hook.
+   */
+  onReady?: (value: T) => void
 }
 
-export function useStorageAsync(key: string, initialValue: MaybeRefOrGetter<string>, storage?: StorageLikeAsync, options?: UseStorageAsyncOptions<string>): RemovableRef<string>
-export function useStorageAsync(key: string, initialValue: MaybeRefOrGetter<boolean>, storage?: StorageLikeAsync, options?: UseStorageAsyncOptions<boolean>): RemovableRef<boolean>
-export function useStorageAsync(key: string, initialValue: MaybeRefOrGetter<number>, storage?: StorageLikeAsync, options?: UseStorageAsyncOptions<number>): RemovableRef<number>
-export function useStorageAsync<T>(key: string, initialValue: MaybeRefOrGetter<T>, storage?: StorageLikeAsync, options?: UseStorageAsyncOptions<T>): RemovableRef<T>
-export function useStorageAsync<T = unknown>(key: string, initialValue: MaybeRefOrGetter<null>, storage?: StorageLikeAsync, options?: UseStorageAsyncOptions<T>): RemovableRef<T>
+export function useStorageAsync(key: string, initialValue: MaybeRefOrGetter<string>, storage?: StorageLikeAsync, options?: UseStorageAsyncOptions<string>): RemovableRef<string> & Promise<RemovableRef<string>>
+export function useStorageAsync(key: string, initialValue: MaybeRefOrGetter<boolean>, storage?: StorageLikeAsync, options?: UseStorageAsyncOptions<boolean>): RemovableRef<boolean> & Promise<RemovableRef<boolean>>
+export function useStorageAsync(key: string, initialValue: MaybeRefOrGetter<number>, storage?: StorageLikeAsync, options?: UseStorageAsyncOptions<number>): RemovableRef<number> & Promise<RemovableRef<number>>
+export function useStorageAsync<T>(key: string, initialValue: MaybeRefOrGetter<T>, storage?: StorageLikeAsync, options?: UseStorageAsyncOptions<T>): RemovableRef<T> & Promise<RemovableRef<T>>
+export function useStorageAsync<T = unknown>(key: string, initialValue: MaybeRefOrGetter<null>, storage?: StorageLikeAsync, options?: UseStorageAsyncOptions<T>): RemovableRef<T> & Promise<RemovableRef<T>>
 
 /**
  * Reactive Storage in with async support.
@@ -37,7 +42,7 @@ export function useStorageAsync<T extends(string | number | boolean | object | n
   initialValue: MaybeRefOrGetter<T>,
   storage: StorageLikeAsync | undefined,
   options: UseStorageAsyncOptions<T> = {},
-): RemovableRef<T> {
+): RemovableRef<T> & Promise<RemovableRef<T>> {
   const {
     flush = 'pre',
     deep = true,
@@ -50,6 +55,7 @@ export function useStorageAsync<T extends(string | number | boolean | object | n
     onError = (e) => {
       console.error(e)
     },
+    onReady,
   } = options
 
   const rawInit: T = toValue(initialValue)
@@ -95,7 +101,12 @@ export function useStorageAsync<T extends(string | number | boolean | object | n
     }
   }
 
-  read()
+  const promise = new Promise((resolve) => {
+    read().then(() => {
+      onReady?.(data.value)
+      resolve(data)
+    })
+  })
 
   if (window && listenToStorageChanges)
     useEventListener(window, 'storage', e => Promise.resolve().then(() => read(e)), { passive: true })
@@ -122,5 +133,10 @@ export function useStorageAsync<T extends(string | number | boolean | object | n
     )
   }
 
-  return data
+  Object.assign(data, {
+    then: promise.then.bind(promise),
+    catch: promise.catch.bind(promise),
+  })
+
+  return data as RemovableRef<T> & Promise<RemovableRef<T>>
 }
