feat(useRefHistory): add shouldCommit (#4471)

JonathanSchndr · antfu · OrbisK · web-flow · commit 18acfabfd31a · 2025-06-10T11:16:24.000Z
Co-authored-by: Anthony Fu &lt;anthonyfu117@hotmail.com&gt;
Co-authored-by: Robin &lt;robin.kehl@singular-it.de&gt;
diff --git a/packages/core/useRefHistory/index.test.ts b/packages/core/useRefHistory/index.test.ts
@@ -298,6 +298,31 @@ describe('useRefHistory - sync', () => {
     expect(history.value[0].snapshot).toBe(2)
     expect(last.value.snapshot).toBe(2)
   })
+
+  it('sync: should respect shouldCommit option', () => {
+    const v = deepRef(0)
+    const { history } = useRefHistory(v, {
+      flush: 'sync',
+      shouldCommit: (oldValue: number | undefined, newValue: number) => newValue > 0,
+    })
+
+    expect(history.value.length).toBe(1)
+    expect(history.value[0].snapshot).toBe(0)
+
+    v.value = -1
+    expect(history.value.length).toBe(1)
+
+    v.value = 2
+    expect(history.value.length).toBe(2)
+    expect(history.value[0].snapshot).toBe(2)
+
+    v.value = -3
+    expect(history.value.length).toBe(2)
+
+    v.value = 4
+    expect(history.value.length).toBe(3)
+    expect(history.value[0].snapshot).toBe(4)
+  })
 })
 
 describe('useRefHistory - pre', () => {
@@ -576,4 +601,32 @@ describe('useRefHistory - pre', () => {
     expect(history.value[0].snapshot).toBe(2)
     expect(last.value.snapshot).toBe(2)
   })
+
+  it('pre: should respect shouldCommit option', async () => {
+    const v = deepRef(0)
+    const { history } = useRefHistory(v, {
+      shouldCommit: (oldValue: number | undefined, newValue: number) => newValue > 0,
+    })
+
+    expect(history.value.length).toBe(1)
+    expect(history.value[0].snapshot).toBe(0)
+
+    v.value = -1
+    await nextTick()
+    expect(history.value.length).toBe(1)
+
+    v.value = 2
+    await nextTick()
+    expect(history.value.length).toBe(2)
+    expect(history.value[0].snapshot).toBe(2)
+
+    v.value = -3
+    await nextTick()
+    expect(history.value.length).toBe(2)
+
+    v.value = 4
+    await nextTick()
+    expect(history.value.length).toBe(3)
+    expect(history.value[0].snapshot).toBe(4)
+  })
 })
diff --git a/packages/core/useRefHistory/index.ts b/packages/core/useRefHistory/index.ts
@@ -45,6 +45,13 @@ export interface UseRefHistoryOptions<Raw, Serialized = Raw> extends Configurabl
    * Deserialize data from the history
    */
   parse?: (v: Serialized) => Raw
+  /**
+   * Function to determine if the commit should proceed
+   * @param oldValue Previous value
+   * @param newValue New value
+   * @returns boolean indicating if commit should proceed
+   */
+  shouldCommit?: (oldValue: Raw | undefined, newValue: Raw) => boolean
 }
 
 export interface UseRefHistoryReturn<Raw, Serialized> extends UseManualRefHistoryReturn<Raw, Serialized> {
@@ -93,6 +100,7 @@ export function useRefHistory<Raw, Serialized = Raw>(
     deep = false,
     flush = 'pre',
     eventFilter,
+    shouldCommit = () => true,
   } = options
 
   const {
@@ -102,6 +110,9 @@ export function useRefHistory<Raw, Serialized = Raw>(
     isActive: isTracking,
   } = pausableFilter(eventFilter)
 
+  // Track the last raw value for shouldCommit comparison
+  let lastRawValue: Raw | undefined = source.value
+
   const {
     ignoreUpdates,
     ignorePrevAsyncUpdates,
@@ -125,6 +136,7 @@ export function useRefHistory<Raw, Serialized = Raw>(
 
     ignoreUpdates(() => {
       source.value = value
+      lastRawValue = value
     })
   }
 
@@ -138,6 +150,10 @@ export function useRefHistory<Raw, Serialized = Raw>(
     // so we do not trigger an extra commit in the async watcher
     ignorePrevAsyncUpdates()
 
+    if (!shouldCommit(lastRawValue, source.value))
+      return
+
+    lastRawValue = source.value
     manualCommit()
   }
 
