chore: add VueUse functions skill and wayfinder cache

Author: imsus

.agents/skills/vueuse-functions/SKILL.md

@@ -0,0 +1,196 @@
+---
+category: Reactivity
+alias: asyncComputed
+---
+
+# computedAsync
+
+Computed for async functions.
+
+## Usage
+
+```ts
+import { computedAsync } from "@vueuse/core";
+import { shallowRef } from "vue";
+
+const name = shallowRef("jack");
+
+const userInfo = computedAsync(
+  async () => {
+    return await mockLookUp(name.value);
+  },
+  null, // initial state
+);
+```
+
+### Evaluation State
+
+Pass a ref to track if the async function is currently evaluating.
+
+```ts
+import { computedAsync } from "@vueuse/core";
+import { shallowRef } from "vue";
+
+const evaluating = shallowRef(false);
+
+const userInfo = computedAsync(
+  async () => {
+    /* your logic */
+  },
+  null,
+  evaluating, // can also be passed via options: { evaluating }
+);
+```
+
+### onCancel
+
+When the computed source changes before the previous async function resolves, you may want to cancel the previous one. Here is an example showing how to incorporate with the fetch API.
+
+```ts
+import { computedAsync } from "@vueuse/core";
+import { shallowRef } from "vue";
+
+const packageName = shallowRef("@vueuse/core");
+
+const downloads = computedAsync(async (onCancel) => {
+  const abortController = new AbortController();
+
+  onCancel(() => abortController.abort());
+
+  return await fetch(`https://api.npmjs.org/downloads/point/last-week/${packageName.value}`, {
+    signal: abortController.signal,
+  })
+    .then((response) => (response.ok ? response.json() : { downloads: "—" }))
+    .then((result) => result.downloads);
+}, 0);
+```
+
+### Lazy
+
+By default, `computedAsync` will start resolving immediately on creation. Specify `lazy: true` to make it start resolving on the first access.
+
+```ts
+import { computedAsync } from "@vueuse/core";
+import { shallowRef } from "vue";
+
+const evaluating = shallowRef(false);
+
+const userInfo = computedAsync(
+  async () => {
+    /* your logic */
+  },
+  null,
+  { lazy: true, evaluating },
+);
+```
+
+### Error Handling
+
+Use the `onError` callback to handle errors from the async function.
+
+```ts
+import { computedAsync } from "@vueuse/core";
+import { shallowRef } from "vue";
+
+const name = shallowRef("jack");
+
+const userInfo = computedAsync(
+  async () => {
+    return await mockLookUp(name.value);
+  },
+  null,
+  {
+    onError(e) {
+      console.error("Failed to fetch user info", e);
+    },
+  },
+);
+```
+
+### Shallow Ref
+
+By default, `computedAsync` uses `shallowRef` internally. Set `shallow: false` to use a deep ref instead.
+
+```ts
+import { computedAsync } from "@vueuse/core";
+import { shallowRef } from "vue";
+
+const name = shallowRef("jack");
+
+const userInfo = computedAsync(
+  async () => {
+    return await fetchNestedData(name.value);
+  },
+  null,
+  { shallow: false }, // enables deep reactivity
+);
+```
+
+## Caveats
+
+- Just like Vue's built-in `computed` function, `computedAsync` does dependency tracking and is automatically re-evaluated when dependencies change. Note however that only dependencies referenced in the first call stack are considered for this. In other words: **Dependencies that are accessed asynchronously will not trigger re-evaluation of the async computed value.**
+
+- As opposed to Vue's built-in `computed` function, re-evaluation of the async computed value is triggered whenever dependencies are changing, regardless of whether its result is currently being tracked or not.
+
+## Type Declarations
+
+```ts
+/**
+ * Handle overlapping async evaluations.
+ *
+ * @param cancelCallback The provided callback is invoked when a re-evaluation of the computed value is triggered before the previous one finished
+ */
+export type AsyncComputedOnCancel = (cancelCallback: Fn) => void;
+export interface AsyncComputedOptions<Lazy = boolean> extends ConfigurableFlushSync {
+  /**
+   * Should value be evaluated lazily
+   *
+   * @default false
+   */
+  lazy?: Lazy;
+  /**
+   * Ref passed to receive the updated of async evaluation
+   */
+  evaluating?: Ref<boolean>;
+  /**
+   * Use shallowRef
+   *
+   * @default true
+   */
+  shallow?: boolean;
+  /**
+   * Callback when error is caught.
+   */
+  onError?: (e: unknown) => void;
+}
+/**
+ * Create an asynchronous computed dependency.
+ *
+ * @see https://vueuse.org/computedAsync
+ * @param evaluationCallback     The promise-returning callback which generates the computed value
+ * @param initialState           The initial state, used until the first evaluation finishes
+ * @param optionsOrRef           Additional options or a ref passed to receive the updates of the async evaluation
+ */
+export declare function computedAsync<T>(
+  evaluationCallback: (onCancel: AsyncComputedOnCancel) => T | Promise<T>,
+  initialState: T,
+  optionsOrRef: AsyncComputedOptions<true>,
+): ComputedRef<T>;
+export declare function computedAsync<T>(
+  evaluationCallback: (onCancel: AsyncComputedOnCancel) => T | Promise<T>,
+  initialState: undefined,
+  optionsOrRef: AsyncComputedOptions<true>,
+): ComputedRef<T | undefined>;
+export declare function computedAsync<T>(
+  evaluationCallback: (onCancel: AsyncComputedOnCancel) => T | Promise<T>,
+  initialState: T,
+  optionsOrRef?: Ref<boolean> | AsyncComputedOptions,
+): Ref<T>;
+export declare function computedAsync<T>(
+  evaluationCallback: (onCancel: AsyncComputedOnCancel) => T | Promise<T>,
+  initialState?: undefined,
+  optionsOrRef?: Ref<boolean> | AsyncComputedOptions,
+): Ref<T | undefined>;
+/** @deprecated use `computedAsync` instead */
+export declare const asyncComputed: typeof computedAsync;
+```

.agents/skills/vueuse-functions/references/computedAsync.md

@@ -0,0 +1,62 @@
+---
+category: Reactivity
+alias: eagerComputed
+---
+
+# computedEager
+
+Eager computed without lazy evaluation.
+
+::: info
+This function will be removed in future version.
+:::
+
+::: tip
+Note💡: If you are using Vue 3.4+, you can use `computed` right away, you no longer need this function.
+In Vue 3.4+, if the computed new value does not change, `computed`, `effect`, `watch`, `watchEffect`, `render` dependencies will not be triggered.
+See: https://github.com/vuejs/core/pull/5912
+:::
+
+Learn more at [Vue: When a computed property can be the wrong tool](https://dev.to/linusborg/vue-when-a-computed-property-can-be-the-wrong-tool-195j).
+
+- Use `computed()` when you have a complex calculation going on, which can actually profit from caching and lazy evaluation and should only be (re-)calculated if really necessary.
+- Use `computedEager()` when you have a simple operation, with a rarely changing return value – often a boolean.
+
+## Usage
+
+```ts
+import { computedEager } from "@vueuse/core";
+
+const todos = ref([]);
+const hasOpenTodos = computedEager(() => !!todos.length);
+
+console.log(hasOpenTodos.value); // false
+toTodos.value.push({ title: "Learn Vue" });
+console.log(hasOpenTodos.value); // true
+```
+
+## Type Declarations
+
+```ts
+export type ComputedEagerOptions = WatchOptionsBase;
+export type ComputedEagerReturn<T = any> = Readonly<ShallowRef<T>>;
+/**
+ *
+ * @deprecated This function will be removed in future version.
+ *
+ * Note: If you are using Vue 3.4+, you can straight use computed instead.
+ * Because in Vue 3.4+, if computed new value does not change,
+ * computed, effect, watch, watchEffect, render dependencies will not be triggered.
+ * refer: https://github.com/vuejs/core/pull/5912
+ *
+ * @param fn effect function
+ * @param options WatchOptionsBase
+ * @returns readonly shallowRef
+ */
+export declare function computedEager<T>(
+  fn: () => T,
+  options?: ComputedEagerOptions,
+): ComputedEagerReturn<T>;
+/** @deprecated use `computedEager` instead */
+export declare const eagerComputed: typeof computedEager;
+```

.agents/skills/vueuse-functions/references/computedEager.md

@@ -0,0 +1,135 @@
+---
+category: Component
+---
+
+# computedInject
+
+Combine `computed` and `inject`. Useful for creating a computed property based on an injected value.
+
+## Usage
+
+In Provider Component
+
+```ts twoslash include main
+import type { InjectionKey, Ref } from "vue";
+import { provide, ref } from "vue";
+
+interface Item {
+  key: number;
+  value: string;
+}
+
+export const ArrayKey: InjectionKey<Ref<Item[]>> = Symbol("symbol-key");
+
+const array = ref([
+  { key: 1, value: "1" },
+  { key: 2, value: "2" },
+  { key: 3, value: "3" },
+]);
+
+provide(ArrayKey, array);
+```
+
+In Receiver Component
+
+```ts
+// @filename: provider.ts
+// @include: main
+// ---cut---
+import { computedInject } from "@vueuse/core";
+
+import { ArrayKey } from "./provider";
+
+const computedArray = computedInject(ArrayKey, (source) => {
+  const arr = [...source.value];
+  arr.unshift({ key: 0, value: "all" });
+  return arr;
+});
+```
+
+### Default Value
+
+You can provide a default value that will be used if the injection key is not provided by a parent component.
+
+```ts
+import { computedInject } from "@vueuse/core";
+
+const computedArray = computedInject(
+  ArrayKey,
+  (source) => {
+    return source.value.map((item) => item.value);
+  },
+  ref([]), // default source value
+);
+```
+
+### Factory Default
+
+Pass `true` as the fourth argument to treat the default value as a factory function.
+
+```ts
+import { computedInject } from "@vueuse/core";
+
+const computedArray = computedInject(
+  ArrayKey,
+  (source) => {
+    return source.value.map((item) => item.value);
+  },
+  () => ref([]), // factory function for default
+  true, // treat default as factory
+);
+```
+
+### Writable Computed
+
+You can also create a writable computed property by passing an object with `get` and `set` functions.
+
+```ts
+import { computedInject } from "@vueuse/core";
+
+const computedArray = computedInject(ArrayKey, {
+  get(source) {
+    return source.value.map((item) => item.value);
+  },
+  set(value) {
+    // handle setting the value
+    console.log("Setting value:", value);
+  },
+});
+```
+
+## Type Declarations
+
+```ts
+export type ComputedInjectGetter<T, K> = (source: T | undefined, oldValue?: K) => K;
+export type ComputedInjectGetterWithDefault<T, K> = (source: T, oldValue?: K) => K;
+export type ComputedInjectSetter<T> = (v: T) => void;
+export interface WritableComputedInjectOptions<T, K> {
+  get: ComputedInjectGetter<T, K>;
+  set: ComputedInjectSetter<K>;
+}
+export interface WritableComputedInjectOptionsWithDefault<T, K> {
+  get: ComputedInjectGetterWithDefault<T, K>;
+  set: ComputedInjectSetter<K>;
+}
+export declare function computedInject<T, K = any>(
+  key: InjectionKey<T> | string,
+  getter: ComputedInjectGetter<T, K>,
+): ComputedRef<K | undefined>;
+export declare function computedInject<T, K = any>(
+  key: InjectionKey<T> | string,
+  options: WritableComputedInjectOptions<T, K>,
+): ComputedRef<K | undefined>;
+export declare function computedInject<T, K = any>(
+  key: InjectionKey<T> | string,
+  getter: ComputedInjectGetterWithDefault<T, K>,
+  defaultSource: T,
+  treatDefaultAsFactory?: false,
+): ComputedRef<K>;
+export declare function computedInject<T, K = any>(
+  key: InjectionKey<T> | string,
+  options: WritableComputedInjectOptionsWithDefault<T, K>,
+  defaultSource: T | (() => T),
+  treatDefaultAsFactory: true,
+): ComputedRef<K>;
+```