feat(useRefHistory): new option eventFilter, new functions useThrottledRefHistory and useDebouncedRefHistory (vitest-dev#740)

Co-authored-by: Anthony Fu <[email protected]>
Co-authored-by: patak <[email protected]>

Author: 3 people

README.md

@@ -7,7 +7,7 @@ Collection of essential Vue Composition Utilities
 <a href="https://www.npmjs.com/package/@vueuse/core" target="__blank"><img src="https://img.shields.io/npm/v/@vueuse/core?color=a1b858&label=" alt="NPM version"></a>
 <a href="https://www.npmjs.com/package/@vueuse/core" target="__blank"><img alt="NPM Downloads" src="https://img.shields.io/npm/dm/@vueuse/core?color=50a36f&label="></a>
 <a href="https://vueuse.org" target="__blank"><img src="https://img.shields.io/static/v1?label=&message=docs%20%26%20demos&color=1e8a7a" alt="Docs & Demos"></a>
-<img alt="Function Count" src="https://img.shields.io/badge/-142%20functions-13708a">
+<img alt="Function Count" src="https://img.shields.io/badge/-144%20functions-13708a">
 <br>
 <a href="https://github.com/vueuse/vueuse" target="__blank"><img alt="GitHub stars" src="https://img.shields.io/github/stars/vueuse/vueuse?style=social"></a>
 </p>

indexes.json

@@ -543,6 +543,13 @@
       "category": "Browser",
       "description": "reactive dark mode with auto data persistence"
     },
+    {
+      "name": "useDebouncedRefHistory",
+      "package": "core",
+      "docs": "https://vueuse.org/core/useDebouncedRefHistory/",
+      "category": "Utilities",
+      "description": "same as [useRefHistory](https://vueuse.org/core/useRefHistory/) but with debounse effect"
+    },
     {
       "name": "useDeviceMotion",
       "package": "core",
@@ -909,6 +916,13 @@
       "category": "Component",
       "description": "shorthand for binding refs to template elements and components inside `v-for`"
     },
+    {
+      "name": "useThrottledRefHistory",
+      "package": "core",
+      "docs": "https://vueuse.org/core/useThrottledRefHistory/",
+      "category": "Utilities",
+      "description": "same as [useRefHistory](https://vueuse.org/core/useRefHistory/) but with throttle effect"
+    },
     {
       "name": "useTimeAgo",
       "package": "core",

packages/core/index.ts

@@ -14,6 +14,7 @@ export * from './useBrowserLocation'
 export * from './useClipboard'
 export * from './useCssVar'
 export * from './useDark'
+export * from './useDebouncedRefHistory'
 export * from './useDeviceMotion'
 export * from './useDeviceOrientation'
 export * from './useDevicePixelRatio'
@@ -63,6 +64,7 @@ export * from './useSpeechRecognition'
 export * from './useStorage'
 export * from './useSwipe'
 export * from './useTemplateRefsList'
+export * from './useThrottledRefHistory'
 export * from './useTimeAgo'
 export * from './useTimestamp'
 export * from './useTitle'

packages/core/useDebouncedRefHistory/demo.vue

@@ -0,0 +1,41 @@
+<script lang="ts" setup>
+import { ref } from '@vue/reactivity'
+import { useCounter } from '@vueuse/shared'
+import dayjs from 'dayjs'
+import { Ref } from 'vue-demi'
+import { useDebouncedRefHistory } from '.'
+
+const format = (ts: number) => dayjs(ts).format()
+const delay: Ref<number> = ref(1000)
+
+const { count, inc, dec } = useCounter()
+const { history, undo, redo, canUndo, canRedo } = useDebouncedRefHistory(count, { capacity: 10, debounce: delay })
+</script>
+
+<template>
+  <div>Count: {{ count }}</div>
+  <button @click="inc()">
+    Increment
+  </button>
+  <button @click="dec()">
+    Decrement
+  </button>
+  <span class="ml-2">/</span>
+  <button :disabled="!canUndo" @click="undo()">
+    Undo
+  </button>
+  <button :disabled="!canRedo" @click="redo()">
+    Redo
+  </button>
+  <span>Delay (in ms):</span>
+  <input v-model="delay" type="number" />
+  <br>
+  <br>
+  <note>History (limited to 10 records for demo)</note>
+  <div class="code-block mt-4">
+    <div v-for="i in history" :key="i.timestamp">
+      <span class="opacity-50 mr-2 font-mono">{{ format(i.timestamp) }}</span>
+      <span class="font-mono">{ value: {{ i.snapshot }} }</span>
+    </div>
+  </div>
+</template>

packages/core/useDebouncedRefHistory/index.md

@@ -0,0 +1,24 @@
+---
+category: Utilities
+---
+
+# useDebouncedRefHistory
+
+Shorthand for `useRefHistory` with debounced filter.
+
+## Usage
+
+This function takes a snapshot of your counter after 1000ms when the value of it starts to change.
+
+```ts
+import { ref } from 'vue' 
+import { useDebouncedRefHistory } from '@vueuse/core'
+
+const counter = ref(0)
+const { history, undo, redo } = useDebouncedRefHistory(counter, { deep: true, debounce: 1000 })
+```
+
+## Related Functions
+
+- `useRefHistory`
+- `useThrottledRefHistory`

packages/core/useDebouncedRefHistory/index.test.ts

@@ -0,0 +1,33 @@
+import { ref } from 'vue-demi'
+import { useSetup } from '../../.test'
+import { useDebouncedRefHistory } from '.'
+
+describe('useDebouncedRefHistory - ', () => {
+  test('take snapshot of data after given time after data was changed', () => {
+    useSetup(() => {
+      const ms = 1000
+      const v = ref(0)
+
+      const { history } = useDebouncedRefHistory(v, { debounce: ms })
+      v.value = 100
+      expect(history.value.length).toBe(1)
+      expect(history.value[0].snapshot).toBe(0)
+
+      setTimeout(() => {
+        expect(history.value.length).toBe(2)
+        expect(history.value[0].snapshot).toBe(100)
+      }, ms)
+    })
+  })
+
+  test('undefined debounce don`t break function', () => {
+    useSetup(() => {
+      const v = ref(0)
+
+      const { history } = useDebouncedRefHistory(v, { deep: false })
+      v.value = 100
+      expect(history.value.length).toBe(2)
+      expect(history.value[0].snapshot).toBe(100)
+    })
+  })
+})

packages/core/useDebouncedRefHistory/index.ts

@@ -0,0 +1,22 @@
+import { MaybeRef, debounceFilter } from '@vueuse/shared'
+import { Ref } from 'vue-demi'
+import { UseRefHistoryOptions, UseRefHistoryReturn, useRefHistory } from '../useRefHistory'
+
+/**
+ * Shorthand for [useRefHistory](https://vueuse.org/useRefHistory) with debounce filter.
+ *
+ * @see https://vueuse.org/useDebouncedRefHistory
+ * @param source
+ * @param options
+ */
+export function useDebouncedRefHistory<Raw, Serialized = Raw>(
+  source: Ref<Raw>,
+  options: Omit<UseRefHistoryOptions<Raw, Serialized>, 'eventFilter'> & { debounce?: MaybeRef<number> } = {},
+): UseRefHistoryReturn<Raw, Serialized> {
+  const filter = options.debounce ? debounceFilter(options.debounce) : undefined
+  const history = useRefHistory(source, { ...options, eventFilter: filter })
+
+  return {
+    ...history,
+  }
+}

packages/core/useRefHistory/index.ts

@@ -1,8 +1,8 @@
-import { Fn, pausableFilter, ignorableWatch } from '@vueuse/shared'
+import { Fn, pausableFilter, ignorableWatch, ConfigurableEventFilter } from '@vueuse/shared'
 import { Ref } from 'vue-demi'
 import { useManualRefHistory, UseRefHistoryRecord, CloneFn } from '../useManualRefHistory'
 
-export interface UseRefHistoryOptions<Raw, Serialized = Raw> {
+export interface UseRefHistoryOptions<Raw, Serialized = Raw> extends ConfigurableEventFilter {
   /**
    * Watch for deep changes, default to false
    *
@@ -149,13 +149,24 @@ export function useRefHistory<Raw, Serialized = Raw>(
   const {
     deep = false,
     flush = 'pre',
+    eventFilter,
   } = options
 
-  const { eventFilter, pause, resume: resumeTracking, isActive: isTracking } = pausableFilter()
-  const { ignoreUpdates, ignorePrevAsyncUpdates, stop } = ignorableWatch(
+  const {
+    eventFilter: composedFilter,
+    pause,
+    resume: resumeTracking,
+    isActive: isTracking,
+  } = pausableFilter(eventFilter)
+
+  const {
+    ignoreUpdates,
+    ignorePrevAsyncUpdates,
+    stop,
+  } = ignorableWatch(
     source,
     commit,
-    { deep, flush, eventFilter },
+    { deep, flush, eventFilter: composedFilter },
   )
 
   function setSource(source: Ref<Raw>, value: Raw) {

packages/core/useThrottledRefHistory/demo.vue

@@ -0,0 +1,41 @@
+<script setup lang="ts">
+import { ref } from '@vue/reactivity'
+import { useCounter } from '@vueuse/shared'
+import dayjs from 'dayjs'
+import { Ref } from 'vue-demi'
+import { useThrottledRefHistory } from '.'
+
+const format = (ts: number) => dayjs(ts).format()
+const delay: Ref<number> = ref(1000)
+
+const { count, inc, dec } = useCounter()
+const { history, undo, redo, canUndo, canRedo } = useThrottledRefHistory(count, { deep: true, throttle: delay })
+</script>
+
+<template>
+  <div>Count: {{ count }}</div>
+  <button @click="inc()">
+    Increment
+  </button>
+  <button @click="dec()">
+    Decrement
+  </button>
+  <span class="ml-2">/</span>
+  <button :disabled="!canUndo" @click="undo()">
+    Undo
+  </button>
+  <button :disabled="!canRedo" @click="redo()">
+    Redo
+  </button>
+  <span>Delay (in ms):</span>
+  <input v-model="delay" type="number" />
+  <br>
+  <br>
+  <note>History (limited to 10 records for demo)</note>
+  <div class="code-block mt-4">
+    <div v-for="i in history" :key="i.timestamp">
+      <span class="opacity-50 mr-2 font-mono">{{ format(i.timestamp) }}</span>
+      <span class="font-mono">{ value: {{ i.snapshot }} }</span>
+    </div>
+  </div>
+</template>

packages/core/useThrottledRefHistory/index.md

@@ -0,0 +1,24 @@
+---
+category: Utilities
+---
+
+# useThrottledRefHistory
+
+Shorthand for `useRefHistory` with throttled filter.
+
+## Usage
+
+This function takes the first snapshot right after the counter's value was changed and the second with a delay of 1000ms.
+
+```ts
+import { ref } from 'vue' 
+import { useThrottledRefHistory } from '@vueuse/core'
+
+const counter = ref(0)
+const { history, undo, redo } = useThrottledRefHistory(counter, { deep: true, throttle: 1000 })
+```
+
+## Related Functions
+
+- `useRefHistory`
+- `useDebouncedRefHistory`

packages/core/useThrottledRefHistory/index.test.ts

@@ -0,0 +1,27 @@
+import { ref } from 'vue-demi'
+import { useSetup } from '../../.test'
+import { useThrottledRefHistory } from '.'
+
+describe('useThrottledRefHistory - sync', () => {
+  test('take first snapshot right after data was changed and second after given time', () => {
+    useSetup(() => {
+      const ms = 1000
+      const v = ref(0)
+
+      const { history } = useThrottledRefHistory(v, { throttle: ms })
+      v.value = 100
+
+      expect(history.value.length).toBe(2)
+      expect(history.value[0].snapshot).toBe(100)
+
+      v.value = 200
+      v.value = 300
+      v.value = 400
+
+      setTimeout(() => {
+        expect(history.value.length).toBe(3)
+        expect(history.value[0].snapshot).toBe(400)
+      }, ms)
+    })
+  })
+})

packages/core/useThrottledRefHistory/index.ts

@@ -0,0 +1,22 @@
+import { MaybeRef, throttleFilter } from '@vueuse/shared'
+import { Ref } from 'vue-demi'
+import { UseRefHistoryOptions, UseRefHistoryReturn, useRefHistory } from '../useRefHistory'
+
+/**
+ * Shorthand for [useRefHistory](https://vueuse.org/useRefHistory) with throttled filter.
+ *
+ * @see https://vueuse.org/useThrottledRefHistory
+ * @param source
+ * @param options
+ */
+export function useThrottledRefHistory<Raw, Serialized = Raw>(
+  source: Ref<Raw>,
+  options: Omit<UseRefHistoryOptions<Raw, Serialized>, 'eventFilter'> & { throttle?: MaybeRef<number> } = {},
+): UseRefHistoryReturn<Raw, Serialized> {
+  const filter = options.throttle ? throttleFilter(options.throttle) : undefined
+  const history = useRefHistory(source, { ...options, eventFilter: filter })
+
+  return {
+    ...history,
+  }
+}

packages/functions.md

@@ -128,12 +128,14 @@
   - [`useAsyncState`](https://vueuse.org/core/useAsyncState/) — reactive async state
   - [`useCounter`](https://vueuse.org/shared/useCounter/) — basic counter with utility functions
   - [`useDebounce`](https://vueuse.org/shared/useDebounce/) — debounce execution of a ref value
+  - [`useDebouncedRefHistory`](https://vueuse.org/core/useDebouncedRefHistory/) — same as [useRefHistory](https://vueuse.org/core/useRefHistory/) but with debounce effect
   - [`useDebounceFn`](https://vueuse.org/shared/useDebounceFn/) — debounce execution of a function
   - [`useEventBus`](https://vueuse.org/core/useEventBus/) — a basic event bus
   - [`useLastChanged`](https://vueuse.org/shared/useLastChanged/) — records the timestamp of the last change
   - [`useManualRefHistory`](https://vueuse.org/core/useManualRefHistory/) — manually track the change history of a ref when the using calls `commit()`
   - [`useRefHistory`](https://vueuse.org/core/useRefHistory/) — track the change history of a ref
   - [`useThrottle`](https://vueuse.org/shared/useThrottle/) — throttle changing of a ref value
+  - [`useThrottledRefHistory`](https://vueuse.org/core/useThrottledRefHistory/) — same as [useRefHistory](https://vueuse.org/core/useRefHistory/) but with throttle effect
   - [`useThrottleFn`](https://vueuse.org/shared/useThrottleFn/) — throttle execution of a function
   - [`useToggle`](https://vueuse.org/shared/useToggle/) — a boolean switcher with utility functions
 

packages/shared/utils/filters.ts

@@ -15,6 +15,11 @@ export type EventFilter<Args extends any[] = any[], This = any> = (
 ) => void
 
 export interface ConfigurableEventFilter {
+  /**
+   * Filter for if events should to be received.
+   *
+   * @see https://vueuse.org/guide/config.html#event-filters
+   */
   eventFilter?: EventFilter
 }