feat(packages/vue): add useCached composable

packages/vue/src/composables/useCached/index.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest';
+import { ref, nextTick } from 'vue';
+import { useCached } from '.';
+
+const arrayEquals = (a: number[], b: number[]) => a.length === b.length && a.every((v, i) => v === b[i]);
+
+describe('useCached', () => {
+  it('default comparator', async () => {
+    const externalValue = ref(0);
+    const cachedValue = useCached(externalValue);
+
+    expect(cachedValue.value).toBe(0);
+
+    externalValue.value = 1;
+    await nextTick();
+    expect(cachedValue.value).toBe(1);
+
+    externalValue.value = 10;
+    await nextTick();
+    expect(cachedValue.value).toBe(10);
+  });
+
+  it('custom array comparator', async () => {
+    const externalValue = ref([1]);
+    const initialValue = externalValue.value;
+
+    const cachedValue = useCached(externalValue, arrayEquals);
+
+    expect(cachedValue.value).toEqual(initialValue);
+
+    externalValue.value = initialValue;
+    await nextTick();
+    expect(cachedValue.value).toEqual(initialValue);
+
+    externalValue.value = [1];
+    await nextTick();
+    expect(cachedValue.value).toEqual(initialValue);
+
+    externalValue.value = [2];
+    await nextTick();
+    expect(cachedValue.value).not.toEqual(initialValue);
+    expect(cachedValue.value).toEqual([2]);
+  });
+});

packages/vue/src/composables/useCached/index.ts

@@ -0,0 +1,36 @@
+import { ref, watch, type Ref, type WatchOptions } from 'vue';
+
+export type Comparator<Value> = (a: Value, b: Value) => boolean;
+
+/**
+ * @name useCached
+ * @category Reactivity
+ * @description Caches the value of an external ref and updates it only when the value changes
+ * 
+ * @param {Ref<T>} externalValue Ref to cache
+ * @param {Comparator<T>} comparator Comparator function to compare the values
+ * @param {WatchOptions} watchOptions Watch options
+ * @returns {Ref<T>} Cached ref
+ * 
+ * @example
+ * const externalValue = ref(0);
+ * const cachedValue = useCached(externalValue);
+ * 
+ * @example
+ * const externalValue = ref(0);
+ * const cachedValue = useCached(externalValue, (a, b) => a === b, { immediate: true });
+ */
+export function useCached<Value = unknown>(
+    externalValue: Ref<Value>,
+    comparator: Comparator<Value> = (a, b) => a === b,
+    watchOptions?: WatchOptions,
+): Ref<Value> {
+    const cached = ref(externalValue.value) as Ref<Value>;
+
+    watch(() => externalValue.value, (value) => {
+        if (!comparator(value, cached.value))
+            cached.value = value;
+    }, watchOptions);
+
+    return cached;
+}