chore: consolidate new foundation and archive v1 (#1495)

v1/packages/mosaic/framework/skills/vueuse-functions/references/useAsyncState.md

@@ -0,0 +1,130 @@
+---
+category: State
+---
+
+# useAsyncState
+
+Reactive async state. Will not block your setup function and will trigger changes once the promise is ready. The state is a `shallowRef` by default.
+
+## Usage
+
+```ts
+import { useAsyncState } from '@vueuse/core';
+import axios from 'axios';
+
+const { state, isReady, isLoading } = useAsyncState(
+  axios.get('https://jsonplaceholder.typicode.com/todos/1').then((t) => t.data),
+  { 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)">Execute with delay</button>
+</template>
+```
+
+## Type Declarations
+
+```ts
+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>;
+  executeImmediate: (...args: Params) => Promise<Data>;
+}
+export type UseAsyncStateReturn<
+  Data,
+  Params extends any[],
+  Shallow extends boolean,
+> = UseAsyncStateReturnBase<Data, Params, Shallow> &
+  PromiseLike<UseAsyncStateReturnBase<Data, Params, Shallow>>;
+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;
+}
+/**
+ * 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
+ */
+export declare 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>;
+```