⬅️ Back to Table of Contents

📄 useAsyncState

📊 Analysis Summary

Metric	Count
🔧 Functions	4
📦 Imports	10
⚡ Async/Await Patterns	4
📐 Interfaces	2
📑 Type Aliases	1

📚 Table of Contents

• Imports
• Async/Await Patterns
• Functions
• Interfaces
• Type Aliases

🛠️ File Location:

📂 packages/core/useAsyncState/index.ts

📦 Imports

Name	Source
MaybeRef	vue
Ref	vue
ShallowRef	vue
UnwrapRef	vue
noop	@vueuse/shared
promiseTimeout	@vueuse/shared
until	@vueuse/shared
deepRef	vue
shallowRef	vue
toValue	vue

---

Async/Await Patterns

Type	Function	Await Expressions	Promise Chains
promise-chain	useAsyncState	none	new Promise(...), until(isLoading).toBe(false).then(() => resolve(shell)).cat...
await-expression	useAsyncState	promiseTimeout(delay), _promise	none
async-function	execute	promiseTimeout(delay), _promise	none
promise-chain	waitUntilIsLoaded	none	new Promise(...), until(isLoading).toBe(false).then(() => resolve(shell)).cat...

---

Functions

useAsyncState(…): UseAsyncStateReturn<Data, Params, Shallow>

Reactive async state. Will not block your setup function and will trigger changes once the promise is ready.

Parameters:

• promise any: The promise / async function to be resolved
• initialState any: The initial state, used until the first evaluation finishes
• options any: No description

See: https://vueuse.org/useAsyncState

Raw JSDoc

/**
 * Reactive async state. Will not block your setup function and will trigger changes once
 * the promise is ready.
 *
 * @see https://vueuse.org/useAsyncState
 * @param promise         The promise / async function to be resolved
 * @param initialState    The initial state, used until the first evaluation finishes
 * @param options
 */

Calls:

• shallowRef (from vue)
• deepRef (from vue)
• toValue (from vue)
• promiseTimeout (from @vueuse/shared)
• promise
• onSuccess
• onError
• execute
• until(isLoading).toBe(false).then(() => resolve(shell)).catch
• waitUntilIsLoaded() .then

Code

export function useAsyncState<Data, Params extends any[] = any[], Shallow extends boolean = true>(
  promise: Promise<Data> | ((...args: Params) => Promise<Data>),
  initialState: MaybeRef<Data>,
  options?: UseAsyncStateOptions<Shallow, Data>,
): UseAsyncStateReturn<Data, Params, Shallow> {
  const {
    immediate = true,
    delay = 0,
    onError = globalThis.reportError ?? noop,
    onSuccess = noop,
    resetOnExecute = true,
    shallow = true,
    throwError,
  } = options ?? {}
  const state = shallow ? shallowRef(initialState) : deepRef(initialState)
  const isReady = shallowRef(false)
  const isLoading = shallowRef(false)
  const error = shallowRef<unknown | undefined>(undefined)

  let executionsCount = 0
  async function execute(delay = 0, ...args: any[]) {
    const executionId = (executionsCount += 1)

    if (resetOnExecute)
      state.value = toValue(initialState)
    error.value = undefined
    isReady.value = false
    isLoading.value = true

    if (delay > 0)
      await promiseTimeout(delay)

    const _promise = typeof promise === 'function'
      ? promise(...args as Params)
      : promise

    try {
      const data = await _promise
      if (executionId === executionsCount) {
        state.value = data
        isReady.value = true
      }
      onSuccess(data)
      return data
    }
    catch (e) {
      if (executionId === executionsCount)
        error.value = e
      onError(e)
      if (throwError)
        throw e
    }
    finally {
      if (executionId === executionsCount)
        isLoading.value = false
    }
  }

  if (immediate) {
    execute(delay)
  }

  const shell: UseAsyncStateReturnBase<Data, Params, Shallow> = {
    state: state as Shallow extends true ? ShallowRef<Data> : Ref<UnwrapRef<Data>>,
    isReady,
    isLoading,
    error,
    execute,
    executeImmediate: (...args: any[]) => execute(0, ...args),
  }

  function waitUntilIsLoaded() {
    return new Promise<UseAsyncStateReturnBase<Data, Params, Shallow>>((resolve, reject) => {
      until(isLoading).toBe(false).then(() => resolve(shell)).catch(reject)
    })
  }

  return {
    ...shell,
    then(onFulfilled, onRejected) {
      return waitUntilIsLoaded()
        .then(onFulfilled, onRejected)
    },
  }
}

Internal helpers

Declared inside another function in this file.

execute(delay: number, args: any[]): Promise<Data>

Parameters:

• delay number
• args any[]

Returns: Promise<Data>

Calls:

• toValue (from vue)
• promiseTimeout (from @vueuse/shared)
• promise
• onSuccess
• onError

Code

async function execute(delay = 0, ...args: any[]) {
    const executionId = (executionsCount += 1)

    if (resetOnExecute)
      state.value = toValue(initialState)
    error.value = undefined
    isReady.value = false
    isLoading.value = true

    if (delay > 0)
      await promiseTimeout(delay)

    const _promise = typeof promise === 'function'
      ? promise(...args as Params)
      : promise

    try {
      const data = await _promise
      if (executionId === executionsCount) {
        state.value = data
        isReady.value = true
      }
      onSuccess(data)
      return data
    }
    catch (e) {
      if (executionId === executionsCount)
        error.value = e
      onError(e)
      if (throwError)
        throw e
    }
    finally {
      if (executionId === executionsCount)
        isLoading.value = false
    }
  }

executeImmediate(args: any[]): Promise<Data>

Parameters:

• args any[]

Returns: Promise<Data>

Calls:

• execute

Code

(...args: any[]) => execute(0, ...args)

waitUntilIsLoaded(): Promise<UseAsyncStateReturnBase<Data, Params, Shallow>>

Returns: Promise<UseAsyncStateReturnBase<Data, Params, Shallow>>

Calls:

• until(isLoading).toBe(false).then(() => resolve(shell)).catch

Code

function waitUntilIsLoaded() {
    return new Promise<UseAsyncStateReturnBase<Data, Params, Shallow>>((resolve, reject) => {
      until(isLoading).toBe(false).then(() => resolve(shell)).catch(reject)
    })
  }

---

Interfaces

UseAsyncStateReturnBase<Data, Params extends any[], Shallow extends boolean>

Interface Code

export interface UseAsyncStateReturnBase<Data, Params extends any[], Shallow extends boolean> {
  state: Shallow extends true ? Ref<Data> : Ref<UnwrapRef<Data>>
  isReady: Ref<boolean>
  isLoading: Ref<boolean>
  error: Ref<unknown>
  execute: (delay?: number, ...args: Params) => Promise<Data | undefined>
  executeImmediate: (...args: Params) => Promise<Data | undefined>
}

Properties

Name	Type	Optional	Description
state	Shallow extends true ? Ref<Data> : Ref<UnwrapRef<Data>>	✗	not shown
isReady	Ref<boolean>	✗	not shown
isLoading	Ref<boolean>	✗	not shown
error	Ref<unknown>	✗	not shown
execute	(delay?: number, ...args: Params) => Promise<Data \| undefined>	✗	not shown
executeImmediate	(...args: Params) => Promise<Data \| undefined>	✗	not shown

UseAsyncStateOptions<Shallow extends boolean, D = any>

Interface Code

export interface UseAsyncStateOptions<Shallow extends boolean, D = any> {
  /**
   * Delay for the first execution of the promise when "immediate" is true. In milliseconds.
   *
   * @default 0
   */
  delay?: number

  /**
   * Execute the promise right after the function is invoked.
   * Will apply the delay if any.
   *
   * When set to false, you will need to execute it manually.
   *
   * @default true
   */
  immediate?: boolean

  /**
   * Callback when error is caught.
   */
  onError?: (e: unknown) => void

  /**
   * Callback when success is caught.
   * @param {D} data
   */
  onSuccess?: (data: D) => void

  /**
   * Sets the state to initialState before executing the promise.
   *
   * This can be useful when calling the execute function more than once (for
   * example, to refresh data). When set to false, the current state remains
   * unchanged until the promise resolves.
   *
   * @default true
   */
  resetOnExecute?: boolean

  /**
   * Use shallowRef.
   *
   * @default true
   */
  shallow?: Shallow
  /**
   *
   * An error is thrown when executing the execute function
   *
   * @default false
   */
  throwError?: boolean
}

Properties

Name	Type	Optional	Description
delay	number	✓	not shown
immediate	boolean	✓	not shown
onError	(e: unknown) => void	✓	not shown
onSuccess	(data: D) => void	✓	not shown
resetOnExecute	boolean	✓	not shown
shallow	Shallow	✓	not shown
throwError	boolean	✓	not shown

---

Type Aliases

UseAsyncStateReturn<Data, Params extends any[], Shallow extends boolean>

type UseAsyncStateReturn<Data, Params extends any[], Shallow extends boolean> = UseAsyncStateReturnBase<Data, Params, Shallow>
    & PromiseLike<UseAsyncStateReturnBase<Data, Params, Shallow>>;

---

Generated by Syntax Scribe