feat(useCached): add options.deepRefs (#4591)

OrbisK · antfu · web-flow · commit 9afeec63a6df · 2025-02-21T11:26:50.000Z
Co-authored-by: Anthony Fu &lt;github@antfu.me&gt;
diff --git a/packages/core/_configurable.ts b/packages/core/_configurable.ts
@@ -39,3 +39,12 @@ export const defaultWindow = /* #__PURE__ */ isClient ? window : undefined
 export const defaultDocument = /* #__PURE__ */ isClient ? window.document : undefined
 export const defaultNavigator = /* #__PURE__ */ isClient ? window.navigator : undefined
 export const defaultLocation = /* #__PURE__ */ isClient ? window.location : undefined
+
+export interface ConfigurableDeepRefs<D extends boolean> {
+  /**
+   * Return deep refs instead of shallow refs.
+   *
+   * @default true - will be changed to `false` by default in the next major
+   */
+  deepRefs?: D
+}
diff --git a/packages/core/useCached/index.test.ts b/packages/core/useCached/index.test.ts
@@ -1,5 +1,5 @@
-import { describe, expect, it } from 'vitest'
-import { ref as deepRef, shallowRef } from 'vue'
+import { describe, expect, it, vi } from 'vitest'
+import { ref as deepRef, isShallow, shallowRef } from 'vue'
 import { nextTwoTick } from '../../.test'
 import { useCached } from './index'
 
@@ -58,4 +58,27 @@ describe('useCached', () => {
     expect(cachedArrayRef.value).not.toBe(initialArrayValue)
     expect(cachedArrayRef.value).toEqual([2])
   })
+
+  describe('should work with options.deepRefs', () => {
+    // todo: change default with next major
+    it.fails('should return shallowRef by default', () => {
+      const value = deepRef(1)
+
+      const cachedValue = useCached(value, vi.fn())
+      expect(isShallow(cachedValue)).toBe(true)
+    })
+    it('should return deepRef if true', () => {
+      const value = deepRef(1)
+
+      const cachedValue = useCached(value, vi.fn(), { deepRefs: true })
+      expect(isShallow(cachedValue)).toBe(false)
+    })
+
+    it('should return shallowRef if false', () => {
+      const value = deepRef(1)
+
+      const cachedValue = useCached(value, vi.fn(), { deepRefs: false })
+      expect(isShallow(cachedValue)).toBe(true)
+    })
+  })
 })
diff --git a/packages/core/useCached/index.ts b/packages/core/useCached/index.ts
@@ -1,12 +1,18 @@
+import type { ConfigurableDeepRefs } from '@vueuse/core/_configurable'
+import type { ShallowOrDeepRef } from '@vueuse/shared'
 import type { Ref, WatchOptions } from 'vue'
-import { ref as deepRef, watch } from 'vue'
+import { createRef } from '@vueuse/shared'
+import { watch } from 'vue'
 
-export function useCached<T>(
+export interface UseCachedOptions<D extends boolean = true> extends ConfigurableDeepRefs<D>, WatchOptions {}
+
+export function useCached<T, D extends boolean = true>(
   refValue: Ref<T>,
   comparator: (a: T, b: T) => boolean = (a, b) => a === b,
-  watchOptions?: WatchOptions,
-): Ref<T> {
-  const cachedValue = deepRef(refValue.value) as Ref<T>
+  options?: UseCachedOptions<D>,
+): UseCachedReturn<T, D> {
+  const { deepRefs = true as D, ...watchOptions } = options || {}
+  const cachedValue = createRef(refValue.value, deepRefs)
 
   watch(() => refValue.value, (value) => {
     if (!comparator(value, cachedValue.value))
@@ -15,3 +21,5 @@ export function useCached<T>(
 
   return cachedValue
 }
+
+export type UseCachedReturn<T = any, D extends boolean = true> = ShallowOrDeepRef<T, D>
diff --git a/packages/core/useSupported/index.ts b/packages/core/useSupported/index.ts
@@ -11,3 +11,5 @@ export function useSupported(callback: () => unknown) {
     return Boolean(callback())
   })
 }
+
+export type UseSupportedReturn = ReturnType<typeof useSupported>
diff --git a/packages/shared/createRef/index.md b/packages/shared/createRef/index.md
@@ -0,0 +1,22 @@
+---
+category: Reactivity
+---
+
+# createRef
+
+Returns a `deepRef` or `shallowRef` depending on the `deep` param.
+
+## Usage
+
+```ts
+import { createRef } from '@vueuse/core'
+import { isShallow, ref } from 'vue'
+
+const initialData = 1
+
+const shallowData = createRef(initialData)
+const deepData = createRef(initialData, true)
+
+isShallow(shallowData) // true
+isShallow(deepData) // false
+```
diff --git a/packages/shared/createRef/index.test.ts b/packages/shared/createRef/index.test.ts
@@ -0,0 +1,44 @@
+import { describe, expect, it, vi } from 'vitest'
+import { isShallow, nextTick, watch } from 'vue'
+import { createRef } from '.'
+
+describe('createRef', () => {
+  it('should return a ref', async () => {
+    const a = createRef(1)
+    expect(a.value).toBe(1)
+    a.value = 5
+    expect(a.value).toBe(5)
+    const b = createRef({ foo: 'bar', baz: 42 })
+    const bSpy = vi.fn()
+    watch(b, bSpy, { deep: true })
+    expect(b.value.foo).toBe('bar')
+    expect(b.value.baz).toBe(42)
+    b.value.foo = 'baz'
+    b.value.baz = 43
+    await nextTick()
+    expect(bSpy).not.toHaveBeenCalled()
+    const c = createRef({ foo: 'bar', baz: 42 }, true)
+    const cSpy = vi.fn()
+    watch(c, cSpy, { deep: true })
+    expect(c.value.foo).toBe('bar')
+    expect(c.value.baz).toBe(42)
+    c.value.foo = 'baz'
+    c.value.baz = 43
+    await nextTick()
+    expect(cSpy).toHaveBeenCalledOnce()
+  })
+
+  describe('deep', () => {
+    it('deep: default - returns shallow', () => {
+      expect(isShallow(createRef(1))).toBe(true)
+    })
+
+    it('deep: true - returns deep', () => {
+      expect(isShallow(createRef(1, true))).toBe(false)
+    })
+
+    it('deep: false - returns shallow', () => {
+      expect(isShallow(createRef(1, false))).toBe(true)
+    })
+  })
+})
diff --git a/packages/shared/createRef/index.ts b/packages/shared/createRef/index.ts
@@ -0,0 +1,26 @@
+import type { Ref, ShallowRef } from 'vue'
+import { ref as deepRef, shallowRef } from 'vue'
+
+export type ShallowOrDeepRef<T = any, D extends boolean = false> = D extends true ? Ref<T> : ShallowRef<T>
+
+/**
+ * Returns a `deepRef` or `shallowRef` depending on the `deep` param.
+ *
+ * @example createRef(1) // ShallowRef<number>
+ * @example createRef(1, false) // ShallowRef<number>
+ * @example createRef(1, true) // Ref<number>
+ * @example createRef("string") // ShallowRef<string>
+ * @example createRef<"A"|"B">("A", true) // Ref<"A"|"B">
+ *
+ * @param value
+ * @param deep
+ * @returns the `deepRef` or `shallowRef`
+ */
+export function createRef<T = any, D extends boolean = false>(value: T, deep?: D): ShallowOrDeepRef<T, D> {
+  if (deep === true) {
+    return deepRef(value) as ShallowOrDeepRef<T, D>
+  }
+  else {
+    return shallowRef(value) as ShallowOrDeepRef<T, D>
+  }
+}
diff --git a/packages/shared/index.ts b/packages/shared/index.ts
@@ -3,6 +3,7 @@ export * from './computedWithControl'
 export * from './createEventHook'
 export * from './createGlobalState'
 export * from './createInjectionState'
+export * from './createRef'
 export * from './createSharedComposable'
 export * from './extendRef'
 export * from './get'

Original file line number	Diff line number	Diff line change
`@@ -11,3 +11,5 @@ export function useSupported(callback: () => unknown) {`
`11`	`11`	`return Boolean(callback())`
`12`	`12`	`})`
`13`	`13`	`}`
	`14`	`+`
	`15`	`+export type UseSupportedReturn = ReturnType<typeof useSupported>`