ads-fe 0.0.1

package/skills/vueuse-functions/references/useAsyncQueue.md

@@ -0,0 +1,136 @@
+---
+category: Utilities
+---
+
+# useAsyncQueue
+
+Executes each asynchronous task sequentially and passes the current task result to the next task.
+
+## Usage
+
+```ts
+import { useAsyncQueue } from '@vueuse/core'
+
+function p1() {
+  return new Promise((resolve) => {
+    setTimeout(() => {
+      resolve(1000)
+    }, 10)
+  })
+}
+
+function p2(result: number) {
+  return new Promise((resolve) => {
+    setTimeout(() => {
+      resolve(1000 + result)
+    }, 20)
+  })
+}
+
+const { activeIndex, result } = useAsyncQueue([p1, p2])
+
+console.log(activeIndex.value) // current pending task index
+
+console.log(result) // the tasks result
+```
+
+### Result State
+
+Each task in the result array has a `state` and `data` property:
+
+```ts
+interface UseAsyncQueueResult<T> {
+  state: 'aborted' | 'fulfilled' | 'pending' | 'rejected'
+  data: T | null
+}
+```
+
+### Interrupt on Failure
+
+By default, if a task fails, subsequent tasks will not be executed. Set `interrupt: false` to continue executing even after failures.
+
+```ts
+const { result } = useAsyncQueue([p1, p2], {
+  interrupt: false, // continue even if p1 fails
+})
+```
+
+### Callbacks
+
+```ts
+const { result } = useAsyncQueue([p1, p2], {
+  onError() {
+    console.log('A task failed')
+  },
+  onFinished() {
+    console.log('All tasks completed (or interrupted)')
+  },
+})
+```
+
+### Abort Signal
+
+You can pass an `AbortSignal` to cancel the queue execution.
+
+```ts
+const controller = new AbortController()
+
+const { result } = useAsyncQueue([p1, p2], {
+  signal: controller.signal,
+})
+
+// Later, abort the queue
+controller.abort()
+```
+
+## Type Declarations
+
+```ts
+export type UseAsyncQueueTask<T> = (...args: any[]) => T | Promise<T>
+type MapQueueTask<T extends any[]> = {
+  [K in keyof T]: UseAsyncQueueTask<T[K]>
+}
+export interface UseAsyncQueueResult<T> {
+  state: "aborted" | "fulfilled" | "pending" | "rejected"
+  data: T | null
+}
+export interface UseAsyncQueueReturn<T> {
+  activeIndex: ShallowRef<number>
+  result: T
+}
+export interface UseAsyncQueueOptions {
+  /**
+   * Interrupt tasks when current task fails.
+   *
+   * @default true
+   */
+  interrupt?: boolean
+  /**
+   * Trigger it when the tasks fails.
+   *
+   */
+  onError?: () => void
+  /**
+   * Trigger it when the tasks ends.
+   *
+   */
+  onFinished?: () => void
+  /**
+   * A AbortSignal that can be used to abort the task.
+   */
+  signal?: AbortSignal
+}
+/**
+ * Asynchronous queue task controller.
+ *
+ * @see https://vueuse.org/useAsyncQueue
+ * @param tasks
+ * @param options
+ */
+export declare function useAsyncQueue<T extends any[], S = MapQueueTask<T>>(
+  tasks: S & Array<UseAsyncQueueTask<any>>,
+  options?: UseAsyncQueueOptions,
+): UseAsyncQueueReturn<{
+  [P in keyof T]: UseAsyncQueueResult<T[P]>
+}>
+```

package/skills/vueuse-functions/references/useAsyncState.md

@@ -0,0 +1,185 @@
+---
+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, error } = useAsyncState(
+  axios
+    .get('https://jsonplaceholder.typicode.com/todos/1')
+    .then(t => t.data),
+  { id: null },
+)
+```
+
+### Return Values
+
+| Property           | Description                                         |
+| ------------------ | --------------------------------------------------- |
+| `state`            | The result of the async function                    |
+| `isReady`          | `true` when the promise has resolved at least once  |
+| `isLoading`        | `true` while the promise is pending                 |
+| `error`            | The error if the promise was rejected               |
+| `execute`          | Re-execute the async function with optional delay   |
+| `executeImmediate` | Re-execute immediately (shorthand for `execute(0)`) |
+
+### Awaiting the Result
+
+The return value is thenable, so you can await it in async functions or `<script setup>`:
+
+```ts
+const { state, isReady } = await useAsyncState(fetchData, null)
+// `state` is now populated, `isReady` is true
+```
+
+### Manual Execution
+
+Set `immediate: false` to prevent automatic execution on creation.
+
+```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>
+```
+
+### Options
+
+```ts
+const { state } = useAsyncState(promise, initialState, {
+  // Execute immediately on creation (default: true)
+  immediate: true,
+  // Delay before first execution in ms (default: 0)
+  delay: 0,
+  // Reset state to initial before each execution (default: true)
+  resetOnExecute: true,
+  // Use shallowRef for state (default: true)
+  shallow: true,
+  // Throw errors instead of catching them (default: false)
+  throwError: false,
+  // Called when promise resolves
+  onSuccess(data) {
+    console.log('Success:', data)
+  },
+  // Called when promise rejects
+  onError(error) {
+    console.error('Error:', error)
+  },
+})
+```
+
+## 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 | undefined>
+  executeImmediate: (...args: Params) => Promise<Data | undefined>
+}
+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>
+```

package/skills/vueuse-functions/references/useAsyncValidator.md

@@ -0,0 +1,70 @@
+---
+category: '@Integrations'
+---
+
+# useAsyncValidator
+
+Wrapper for [`async-validator`](https://github.com/yiminghe/async-validator).
+
+## Install
+
+```bash
+npm i async-validator@^4
+```
+
+## Usage
+
+```ts
+import { useAsyncValidator } from '@vueuse/integrations/useAsyncValidator'
+```
+
+## Type Declarations
+
+```ts
+export type AsyncValidatorError = Error & {
+  errors: ValidateError[]
+  fields: Record<string, ValidateError[]>
+}
+export interface UseAsyncValidatorExecuteReturn {
+  pass: boolean
+  errors: AsyncValidatorError["errors"] | undefined
+  errorInfo: AsyncValidatorError | null
+  errorFields: AsyncValidatorError["fields"] | undefined
+}
+export interface UseAsyncValidatorReturn {
+  pass: ShallowRef<boolean>
+  isFinished: ShallowRef<boolean>
+  errors: ComputedRef<AsyncValidatorError["errors"] | undefined>
+  errorInfo: ShallowRef<AsyncValidatorError | null>
+  errorFields: ComputedRef<AsyncValidatorError["fields"] | undefined>
+  execute: () => Promise<UseAsyncValidatorExecuteReturn>
+}
+export interface UseAsyncValidatorOptions {
+  /**
+   * @see https://github.com/yiminghe/async-validator#options
+   */
+  validateOption?: ValidateOption
+  /**
+   * The validation will be triggered right away for the first time.
+   * Only works when `manual` is not set to true.
+   *
+   * @default true
+   */
+  immediate?: boolean
+  /**
+   * If set to true, the validation will not be triggered automatically.
+   */
+  manual?: boolean
+}
+/**
+ * Wrapper for async-validator.
+ *
+ * @see https://vueuse.org/useAsyncValidator
+ * @see https://github.com/yiminghe/async-validator
+ */
+export declare function useAsyncValidator(
+  value: MaybeRefOrGetter<Record<string, any>>,
+  rules: MaybeRefOrGetter<Rules>,
+  options?: UseAsyncValidatorOptions,
+): UseAsyncValidatorReturn & PromiseLike<UseAsyncValidatorReturn>
+```

package/skills/vueuse-functions/references/useAuth.md

@@ -0,0 +1,123 @@
+---
+category: '@Firebase'
+---
+
+# useAuth
+
+Reactive [Firebase Auth](https://firebase.google.com/docs/auth) binding. It provides a reactive `user` and `isAuthenticated` so you
+can easily react to changes in the users' authentication status.
+
+## Usage
+
+```vue
+<script setup lang="ts">
+import { useAuth } from '@vueuse/firebase/useAuth'
+import { initializeApp } from 'firebase/app'
+import { getAuth, GoogleAuthProvider, signInWithPopup } from 'firebase/auth'
+
+const app = initializeApp({ /* config */ })
+const auth = getAuth(app)
+const { isAuthenticated, user } = useAuth(auth)
+
+const signIn = () => signInWithPopup(auth, new GoogleAuthProvider())
+</script>
+
+<template>
+  <pre v-if="isAuthenticated">{{ user }}</pre>
+  <div v-else>
+    <button @click="signIn">
+      Sign In with Google
+    </button>
+  </div>
+</template>
+```
+
+## Return Values
+
+| Name              | Type                   | Description                                               |
+| ----------------- | ---------------------- | --------------------------------------------------------- |
+| `user`            | `Ref<User \| null>`    | The current Firebase user, or `null` if not authenticated |
+| `isAuthenticated` | `ComputedRef<boolean>` | Whether a user is currently authenticated                 |
+
+The composable automatically updates when the user's ID token changes (including sign-in, sign-out, and token refresh events) using Firebase's `onIdTokenChanged` listener.
+
+## Type Declarations
+
+```ts
+export interface UseFirebaseAuthOptions {
+  isAuthenticated: ComputedRef<boolean>
+  user: Ref<User | null>
+}
+/**
+ * Reactive Firebase Auth binding
+ *
+ * @see https://vueuse.org/useAuth
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function useAuth(auth: Auth): {
+  isAuthenticated: ComputedRef<boolean>
+  user: Ref<
+    {
+      readonly emailVerified: boolean
+      readonly isAnonymous: boolean
+      readonly metadata: {
+        readonly creationTime?: string | undefined
+        readonly lastSignInTime?: string | undefined
+      }
+      readonly providerData: {
+        readonly displayName: string | null
+        readonly email: string | null
+        readonly phoneNumber: string | null
+        readonly photoURL: string | null
+        readonly providerId: string
+        readonly uid: string
+      }[]
+      readonly refreshToken: string
+      readonly tenantId: string | null
+      delete: () => Promise<void>
+      getIdToken: (forceRefresh?: boolean) => Promise<string>
+      getIdTokenResult: (forceRefresh?: boolean) => Promise<IdTokenResult>
+      reload: () => Promise<void>
+      toJSON: () => object
+      readonly displayName: string | null
+      readonly email: string | null
+      readonly phoneNumber: string | null
+      readonly photoURL: string | null
+      readonly providerId: string
+      readonly uid: string
+    } | null,
+    | User
+    | {
+        readonly emailVerified: boolean
+        readonly isAnonymous: boolean
+        readonly metadata: {
+          readonly creationTime?: string | undefined
+          readonly lastSignInTime?: string | undefined
+        }
+        readonly providerData: {
+          readonly displayName: string | null
+          readonly email: string | null
+          readonly phoneNumber: string | null
+          readonly photoURL: string | null
+          readonly providerId: string
+          readonly uid: string
+        }[]
+        readonly refreshToken: string
+        readonly tenantId: string | null
+        delete: () => Promise<void>
+        getIdToken: (forceRefresh?: boolean) => Promise<string>
+        getIdTokenResult: (forceRefresh?: boolean) => Promise<IdTokenResult>
+        reload: () => Promise<void>
+        toJSON: () => object
+        readonly displayName: string | null
+        readonly email: string | null
+        readonly phoneNumber: string | null
+        readonly photoURL: string | null
+        readonly providerId: string
+        readonly uid: string
+      }
+    | null
+  >
+}
+```

package/skills/vueuse-functions/references/useAverage.md

@@ -0,0 +1,36 @@
+---
+category: '@Math'
+---
+
+# useAverage
+
+Get the average of an array reactively.
+
+## Usage
+
+```ts
+import { useAverage } from '@vueuse/math'
+
+const list = ref([1, 2, 3])
+const averageValue = useAverage(list) // Ref<2>
+```
+
+```ts
+import { useAverage } from '@vueuse/math'
+
+const a = ref(1)
+const b = ref(3)
+
+const averageValue = useAverage(a, b) // Ref<2>
+```
+
+## Type Declarations
+
+```ts
+export declare function useAverage(
+  array: MaybeRefOrGetter<MaybeRefOrGetter<number>[]>,
+): ComputedRef<number>
+export declare function useAverage(
+  ...args: MaybeRefOrGetter<number>[]
+): ComputedRef<number>
+```