feat(useCloned): new function

packages/core/index.ts

@@ -18,6 +18,7 @@ export * from './useBroadcastChannel'
 export * from './useBrowserLocation'
 export * from './useCached'
 export * from './useClipboard'
+export * from './useCloned'
 export * from './useColorMode'
 export * from './useConfirmDialog'
 export * from './useCssVar'

packages/core/useCloned/demo.vue

@@ -0,0 +1,16 @@
+<script setup lang="ts">
+import { useCloned } from '@vueuse/core'
+
+const template = { fruit: 'banana', drink: 'water' }
+
+const { cloned, sync } = useCloned(template)
+</script>
+
+<template>
+  <input v-model="cloned.fruit" type="text">
+  <input v-model="cloned.drink" type="text">
+
+  <button @click="sync()">
+    reset
+  </button>
+</template>

packages/core/useCloned/index.md

@@ -0,0 +1,61 @@
+---
+category: Utilities
+---
+
+# useCloned
+
+Reactive partial clone.
+
+## Usage
+```ts
+import { useCloned } from '@vueuse/core/useCloned'
+
+const originData = ref({
+  key: 'value'
+})
+
+const { cloned, stop } = useCloned(originData)
+
+originData.key = 'some new value'
+
+console.log(cloned.value.key) // 'some new value'
+
+stop()
+```
+
+## Manual cloning
+```ts
+import { useCloned } from '@vueuse/core/useCloned'
+
+const data = ref({
+  key: 'value'
+})
+
+const { cloned, sync } = useCloned(data, { manual: true })
+
+data.key = 'manual'
+
+console.log(cloned.value.key) // 'value'
+
+sync()
+
+console.log(cloned.value.key)// 'manual'
+```
+
+## Custom clone function usage
+```ts
+import { useCloned } from '@vueuse/core/useCloned'
+
+const data = ref({
+  key: 'value'
+})
+
+const { cloned, sync } = useCloned(data, {
+  cloneFunction: (source, cloned) => ({ ...source, isCloned: true })
+})
+
+data.value.key = 'clone it'
+
+console.log(cloned.value.isCloned) // true
+console.log(cloned.value.key) // 'clone it'
+```

packages/core/useCloned/index.test.ts

@@ -0,0 +1,76 @@
+import { useCloned } from '@vueuse/core'
+import { expect } from 'vitest'
+import { nextTick, ref } from 'vue-demi'
+
+describe('useCloned', () => {
+  it('works with simple objects', () => {
+    const data = { test: 'test' }
+
+    const { cloned, sync } = useCloned(data)
+
+    expect(cloned.value).toEqual(data)
+
+    cloned.value = { test: 'failed' }
+
+    sync()
+
+    expect(cloned.value).toEqual(data)
+  })
+
+  it('works with refs', async () => {
+    const data = ref({ test: 'test' })
+
+    const { cloned } = useCloned(data)
+
+    data.value.test = 'success'
+
+    await nextTick()
+
+    expect(cloned.value).toEqual(data.value)
+  })
+
+  it('works with refs and manual sync', async () => {
+    const data = ref({ test: 'test' })
+
+    const { cloned, sync } = useCloned(data, { manual: true })
+
+    data.value.test = 'success'
+
+    expect(cloned.value).not.toEqual(data.value)
+
+    sync()
+
+    expect(cloned.value).toEqual(data.value)
+  })
+
+  it('works like partial cloning', async () => {
+    const data = ref({ test: 'test' })
+
+    const { cloned } = useCloned<Record<string, unknown>>(data)
+
+    cloned.value.check = 'value'
+
+    data.value.test = 'partial'
+
+    await nextTick()
+
+    expect(cloned.value.check).toBe('value')
+    expect(cloned.value.test).toBe('partial')
+  })
+
+  it('works with custom clone function', async () => {
+    const data = ref({ test: 'test' })
+
+    const { cloned } = useCloned<Record<string, any>>(data, { cloneFunction: (source, cloned) => ({ ...cloned, ...source, proxyTest: true }) })
+
+    cloned.value.check = 'value'
+
+    data.value.test = 'partial'
+
+    await nextTick()
+
+    expect(cloned.value.check).toBe('value')
+    expect(cloned.value.test).toBe('partial')
+    expect(cloned.value.proxyTest).toBe(true)
+  })
+})

packages/core/useCloned/index.ts

@@ -0,0 +1,43 @@
+import type { MaybeRef } from '@vueuse/shared'
+import type { Ref, WatchStopHandle } from 'vue-demi'
+import { isRef, ref, unref, watch } from 'vue-demi'
+
+export interface UseClonedOptions<T extends Record<any, any> = Record<any, any>> {
+  /**
+   * sync source only by function
+   */
+  manual?: boolean
+  /**
+   * Custom clone function should return new value for cloned data
+   */
+  cloneFunction?: (source: Partial<T>, cloned: Partial<T>) => Partial<T> | T
+}
+
+export function useCloned<T extends Record<any, any> = Record<any, any>>(source: Ref<Partial<T>>, options: UseClonedOptions & { manual: true }): { cloned: Ref<T>; sync: () => void }
+export function useCloned<T extends Record<any, any> = Record<any, any>>(source: Ref<Partial<T>>, options?: UseClonedOptions & { manual: false } | Omit<UseClonedOptions, 'manual'>): { cloned: Ref<T>; sync: () => void; stop: WatchStopHandle }
+export function useCloned<T extends Record<any, any> = Record<any, any>>(source: Partial<T>): { cloned: Ref<T>; sync: () => void; stop: WatchStopHandle }
+export function useCloned<T extends Record<any, any> = Record<any, any>>(source: MaybeRef<Partial<T>>, options: UseClonedOptions = {}) {
+  const cloned = ref<T>({} as T)
+
+  const { manual, cloneFunction } = options
+
+  let stopWatcher: undefined | WatchStopHandle
+
+  if (!manual && isRef(source))
+    stopWatcher = watch(source, sync, { immediate: true, deep: true })
+  else
+    sync()
+
+  function sync() {
+    if (cloneFunction) {
+      cloned.value = cloneFunction(unref(source), cloned.value)
+
+      return
+    }
+
+    for (const key in unref(source))
+      cloned.value[key] = unref(source)[key as keyof T]
+  }
+
+  return { cloned, sync, ...(stopWatcher && { stop: stopWatcher }) } as any
+}