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,60 @@
+---
+category: Utilities
+---
+
+# useCloned
+
+Reactive partial clone.
+
+## Usage
+```ts
+import { useCloned } from '@vueuse/core/useCloned'
+
+const originData = ref({
+  key: 'value'
+})
+
+const { cloned } = useCloned(originData)
+
+originData.key = 'some new value'
+
+console.log(cloned.value.key) // 'some new value'
+
+```
+
+## 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,85 @@
+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 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)
+  })
+
+  it('works with watch options', async () => {
+    const data = ref({ test: 'test' })
+
+    const { cloned } = useCloned(data, { watchOptions: { immediate: false, deep: false } })
+
+    await nextTick()
+
+    // test immediate: false
+    expect(cloned.value).toEqual({})
+
+    data.value.test = 'not valid'
+
+    await nextTick()
+
+    // test deep: false
+    expect(cloned.value).toEqual({})
+
+    data.value = { test: 'valid' }
+
+    await nextTick()
+
+    expect(cloned.value).toEqual(data.value)
+  })
+})

packages/core/useCloned/index.ts

@@ -0,0 +1,41 @@
+import type { MaybeRef } from '@vueuse/shared'
+import type { WatchOptions } 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: T, cloned: T) => T
+  /**
+   * Options for watcher
+   *
+   * @default { immediate: true, deep: true }
+   */
+  watchOptions?: WatchOptions
+}
+
+export function useCloned<T extends Record<any, any> = Record<any, any>>(source: MaybeRef<T>, options: UseClonedOptions = {}) {
+  const cloned = ref<T>({} as T)
+
+  const { manual, cloneFunction, watchOptions = { immediate: true, deep: true } } = options
+
+  if (!manual && isRef(source))
+    watch(source, sync, watchOptions)
+  else
+    sync()
+
+  function defaultCloning() {
+    return JSON.parse(JSON.stringify(unref(source)))
+  }
+
+  function sync() {
+    cloned.value = cloneFunction ? cloneFunction(unref(source), cloned.value) : defaultCloning()
+  }
+
+  return { cloned, sync }
+}