feat(useThrottle): trailing option, useThrottledRefHistory updated (

vitest-dev#760)

Co-authored-by: Anthony Fu <anthonyfu117@hotmail.com>
Co-authored-by: patak <matias.capeletto@gmail.com>

packages/core/useThrottledRefHistory/demo.vue

@@ -11,7 +11,7 @@ const delay: Ref<number> = ref(1000)
 const { count, inc, dec } = useCounter()
 const { history, undo, redo, canUndo, canRedo } = useThrottledRefHistory(
   count, {
-    deep: true, throttle: delay, capacity: 10,
+    deep: true, throttle: delay, capacity: 10, trailing: true,
   })
 </script>
 

packages/core/useThrottledRefHistory/index.ts

@@ -11,9 +11,10 @@ import { UseRefHistoryOptions, UseRefHistoryReturn, useRefHistory } from '../use
  */
 export function useThrottledRefHistory<Raw, Serialized = Raw>(
   source: Ref<Raw>,
-  options: Omit<UseRefHistoryOptions<Raw, Serialized>, 'eventFilter'> & { throttle?: MaybeRef<number> } = {},
+  options: Omit<UseRefHistoryOptions<Raw, Serialized>, 'eventFilter'> & { throttle?: MaybeRef<number>; trailing?: boolean } = {},
 ): UseRefHistoryReturn<Raw, Serialized> {
-  const filter = options.throttle ? throttleFilter(options.throttle) : undefined
+  const { throttle = 200, trailing = true } = options
+  const filter = throttleFilter(throttle, trailing)
   const history = useRefHistory(source, { ...options, eventFilter: filter })
 
   return {

packages/shared/throttledWatch/index.ts

@@ -6,7 +6,7 @@ export interface ThrottledWatchOptions<Immediate> extends WatchOptions<Immediate
   throttle?: MaybeRef<number>
 }
 
-// overlads
+// overloads
 export function throttledWatch<T extends Readonly<WatchSource<unknown>[]>, Immediate extends Readonly<boolean> = false>(sources: T, cb: WatchCallback<MapSources<T>, MapOldSources<T, Immediate>>, options?: ThrottledWatchOptions<Immediate>): WatchStopHandle
 export function throttledWatch<T, Immediate extends Readonly<boolean> = false>(source: WatchSource<T>, cb: WatchCallback<T, Immediate extends true ? T | undefined : T>, options?: ThrottledWatchOptions<Immediate>): WatchStopHandle
 export function throttledWatch<T extends object, Immediate extends Readonly<boolean> = false>(source: T, cb: WatchCallback<T, Immediate extends true ? T | undefined : T>, options?: ThrottledWatchOptions<Immediate>): WatchStopHandle
@@ -15,10 +15,11 @@ export function throttledWatch<T extends object, Immediate extends Readonly<bool
 export function throttledWatch<Immediate extends Readonly<boolean> = false>(
   source: any,
   cb: any,
-  options: ThrottledWatchOptions<Immediate> = {},
+  options: ThrottledWatchOptions<Immediate> & { trailing?: boolean } = {},
 ): WatchStopHandle {
   const {
     throttle = 0,
+    trailing = true,
     ...watchOptions
   } = options
 
@@ -27,7 +28,7 @@ export function throttledWatch<Immediate extends Readonly<boolean> = false>(
     cb,
     {
       ...watchOptions,
-      eventFilter: throttleFilter(throttle),
+      eventFilter: throttleFilter(throttle, trailing),
     },
   )
 }

packages/shared/useThrottle/demo.vue

@@ -2,8 +2,9 @@
 import { ref, watch } from 'vue-demi'
 import { useThrottle } from '.'
 
+const trailing = ref(true)
 const input = ref('')
-const throttled = useThrottle(input, 1000)
+const throttled = useThrottle(input, 1000, trailing.value)
 const updated = ref(0)
 
 watch(throttled, () => {
@@ -18,5 +19,6 @@ watch(throttled, () => {
 
     <p>Throttled: {{ throttled }}</p>
     <p>Times Updated: {{ updated }}</p>
+    <p>Trailing: {{ trailing }}</p>
   </div>
 </template>

packages/shared/useThrottle/index.md

@@ -15,6 +15,18 @@ const input = ref('')
 const throttled = useThrottle(input, 1000)
 ```
 
+### Trailing
+
+If you don't want to watch trailing changes, set 3rd param `false` (it's `true` by default):
+
+```js
+import { useThrottle } from '@vueuse/core'
+
+const input = ref('')
+const throttled = useThrottle(input, 1000, false)
+```
+
+
 ## Related Functions
 
 - `useThrottle`

packages/shared/useThrottle/index.ts

@@ -5,17 +5,19 @@ import { useThrottleFn } from '../useThrottleFn'
  * Throttle execution of a function. Especially useful for rate limiting
  * execution of handlers on events like resize and scroll.
  *
+ * @param value Ref value to be watched with throttle effect
  * @param  delay  A zero-or-greater delay in milliseconds. For event callbacks, values around 100 or 250 (or even higher) are most useful.
+ * @param [trailing=true] if true, update the value again after the delay time is up
  */
-export function useThrottle<T>(value: Ref<T>, delay = 200) {
+export function useThrottle<T>(value: Ref<T>, delay = 200, trailing = true) {
   if (delay <= 0)
     return value
 
   const throttled: Ref<T> = ref(value.value as T) as Ref<T>
 
   const updater = useThrottleFn(() => {
     throttled.value = value.value
-  }, delay)
+  }, delay, trailing)
 
   watch(value, () => updater())
 

packages/shared/useThrottleFn/index.ts

@@ -8,6 +8,8 @@ import { createFilterWrapper, FunctionArgs, throttleFilter, MaybeRef } from '../
  *                                    to `callback` when the throttled-function is executed.
  * @param   ms             A zero-or-greater delay in milliseconds. For event callbacks, values around 100 or 250 (or even higher) are most useful.
  *
+ * @param [trailing=true] if true, call fn again after the time is up
+ *
  * @return  A new, throttled, function.
  */
 export function useThrottleFn<T extends FunctionArgs>(fn: T, ms: MaybeRef<number> = 200, trailing = true): T {