Ignorable watch
VueUse's useRefHistory
lets you watch a ref and keep track of its history, providing undo and redo functionality. It uses flush 'pre'
by default to watching the source ref. Its semantics are aligned with the standard watch
, creating history points that bundle all the changes done to the source value during the same "tick". The use of flush 'sync'
is discouraged in the Vue docs. Being able to buffers invalidated effects is important for performance, but also to avoid breaking invariants when generating spurious history points in updates that require several operations. One big caveat for example is that when deeply sync watching an array, a single splice call generates up to three triggers.
Let's look at a simplified useUndo
composable that only allows undoing of ref changes to understand how we were able to do it and how ignorableWatch
was distilled so we can use the same technique when building other composables. The main difficulty to implement ref history is how to update the source when undoing without triggering the internal watch and re-adding this state to the history. If we only need to support sync flushing, it can be implemented in a straight forward way using a guard.
function useSyncUndo(source, options) {
const history = ref([source.value])
const undoing = ref(false)
const _commit = () => {
history.value.unshift(source.value)
}
const _undo = () => {
if (history.value.length > 1) {
history.value.shift()
source.value = history.value[0]
}
}
const stop = watch(
source,
() => {
if (!undoing.value) {
_commit()
}
},
{ ...options, flush: 'sync' }
)
function undo() {
undoing.value = true
_undo()
undoing.value = false
}
return { undo, history, stop }
}
This technique doesn't work with flush pre and post because the sync change to the source in the current "tick" triggers the watch but it is flushed together with other effects after the tick is over. So we need a way to flag certain updates to the source and ignore them after the watch is called. We can achieve this using a double watch.
function ignorableWatch(source,cb,options) {
const ignoreCount = ref(0)
const syncCount = ref(0)
const syncStop = watch(
source,
() => {
syncCount.value++
},
{ ...options, flush: 'sync' },
)
const stop = watch( source,
(...args) => {
const ignore = ignoreCount.value > 0 &&
ignoreCount.value === syncCount.value
ignoreCount.value = 0
syncCount.value = 0
if (!ignore) {
cb(...args)
}
},
options
)
const ignoreUpdates = (updater) => {
const prev = syncCount.value
updater()
const changes = syncCount.value - prev
// Add sync changes done in updater
ignoreCount.value += changes
}
const ignorePrevAsyncUpdates = () => {
// All sync changes til are ignored
ignoreCount.value = syncCount.value
}
return {
ignoreUpdates,
ignorePreAsyncUpdates,
stop: () => {
syncStop()
stop()
}
}
}
The syncCount is incremented in sync with every change to the source ref value using a watch with flush 'sync'
. This lets us know how many times the ref has been modified in this "tick". When calling ignoreUpdates
, all sync changes to the source in the updater function will be counted and added to the ignoreCount
. When the second watch flushes at the end of the tick, we know if there were more changes done to the source than the ones that were ignored so we can filter out the triggered effect if all the changes in the "tick" were marked to be ignored.
VueUse's ignorableWatch
follows this idea supporting all flush modes. It is implemented using the double watch scheme for flush 'pre'
and 'post'
, a sync watch allows us to count changes and ignore the triggered effect if all operations were flagged to be ignored in the current "tick". For 'sync'
, a single watch with a guard is used to implement ignoreUpdates
and ignorePrevAsyncUpdates
is a no-op provided so users can write generic code that does not depend on the flush
mode.
There is a related utility in VueUse called pausableWatch that exposes two methods pause()
and resume()
allowing to ignore the watch while it is paused. ignorableWatch
is different from it because in pausableWatch
effects are ignored if the watch is paused at flush time.
const source = ref(0)
const { pause, resume } = pausableWatch(
source,
() => {
console.log(source.value)
}
)
pause()
source.value = 1 // paused while changed
resume()
await nextTick()
// but it is not paused at flush time,
// so it still logs 1
When we use ignorableWatch
, the effects are ignored when they are triggered.
const source = ref(0)
const { ignoreUpdates } = ignorableWatch(
source,
() => {
console.log(source.value)
}
)
ignoreUpdates( () => {
source.value = 1
})
await nextTick()
// nothing... the watch ignored the change
Now that we have ignorableWatch
in our tool belt, we can build a generic version of the useUndo
composable that supports all flushing modes. We leave _commit
and _undo
untouched so we can focus on how to modify the watched source without triggering when undoing.
function useUndo(source, options) {
const history = ref([source.value])
const _commit = () => {
history.value.unshift(source.value)
}
const _undo = () => {
if (history.value.length > 1) {
history.value.shift()
source.value = history.value[0]
}
}
const {
ignoreUpdates,
ignorePrevAsyncUpdates,
stop
} = ignorableWatch(source,_commit,options)
const undo = () => {
ignorePrevAsyncUpdates()
ignoreUpdates(_undo)
}
return { undo, history, stop }
}
You can check the implementation of useRefHistory
to see how ignorableWatch
is used in the lib. In it, other useful features to deal with ref history are provided.
I learned about the importance of flush 'pre'
while developing undo support for Layoutit Grid. I was later able to upstream some of this experience to VueUse, and ignorableWatch
was spawned organically as part of this process. This is a good example of how working in Apps using Vue Composition API facilitates the discovery and sharing of reusable pieces.
Ignorable Watch
VueUse's ignorableWatch, useRefHistory and watch flush modes
History and Persistence
useRefHistory and useLocalStorage as building blocks to create new composables
Mark Raw Optimization
Using markRaw to optimize VueUse's useRefHistory composable