feat(useAsyncState): add executeImmediate with the same type as the promise fn (#4716)

davidglezz · web-flow · commit 827403eb31ee · 2025-06-19T08:01:45.000Z
Signed-off-by: davidglezz &lt;davidgg666@gmail.com&gt;
diff --git a/packages/core/useAsyncState/index.md b/packages/core/useAsyncState/index.md
@@ -19,3 +19,32 @@ const { state, isReady, isLoading } = useAsyncState(
   { id: null },
 )
 ```
+
+### Manually trigger the async function
+
+You can also trigger it manually. This is useful when you want to control when the async function is executed.
+
+```vue
+<script setup lang="ts">
+import { useAsyncState } from '@vueuse/core'
+
+const { state, execute, executeImmediate } = useAsyncState(action, '', { immediate: false })
+
+async function action(event) {
+  await new Promise(resolve => setTimeout(resolve, 500))
+  return `${event.target.textContent} clicked!`
+}
+</script>
+
+<template>
+  <p>State: {{ state }}</p>
+
+  <button class="button" @click="executeImmediate">
+    Execute now
+  </button>
+
+  <button class="ml-2 button" @click="event => execute(500, event.target)">
+    Execute with delay
+  </button>
+</template>
+```
diff --git a/packages/core/useAsyncState/index.test.ts b/packages/core/useAsyncState/index.test.ts
@@ -27,6 +27,13 @@ describe('useAsyncState', () => {
     expect(state.value).toBe(2)
   })
 
+  it('should executeImmediate', async () => {
+    const { executeImmediate, state } = useAsyncState(p1, 0)
+    expect(state.value).toBe(0)
+    await executeImmediate(2)
+    expect(state.value).toBe(2)
+  })
+
   it('should work with await', async () => {
     const asyncState = useAsyncState(p1, 0, { immediate: true })
     expect(asyncState.isLoading.value).toBeTruthy()
diff --git a/packages/core/useAsyncState/index.ts b/packages/core/useAsyncState/index.ts
@@ -8,6 +8,7 @@ export interface UseAsyncStateReturnBase<Data, Params extends any[], Shallow ext
   isLoading: Ref<boolean>
   error: Ref<unknown>
   execute: (delay?: number, ...args: Params) => Promise<Data>
+  executeImmediate: (...args: Params) => Promise<Data>
 }
 
 export type UseAsyncStateReturn<Data, Params extends any[], Shallow extends boolean> =
@@ -16,7 +17,7 @@ export type UseAsyncStateReturn<Data, Params extends any[], Shallow extends bool
 
 export interface UseAsyncStateOptions<Shallow extends boolean, D = any> {
   /**
-   * Delay for executing the promise. In milliseconds.
+   * Delay for the first execution of the promise when "immediate" is true. In milliseconds.
    *
    * @default 0
    */
@@ -140,6 +141,7 @@ export function useAsyncState<Data, Params extends any[] = any[], Shallow extend
     isLoading,
     error,
     execute,
+    executeImmediate: (...args: any[]) => execute(0, ...args),
   }
 
   function waitUntilIsLoaded() {
