Helper Functions
opaqueObject
opaqueObject
marks an object in an observable as opaque so that it will be treated as a primitive, so that properties inside the opaque object will not be observable.
This is useful for storing DOM or React elements or other large objects in an observable when you don’t care about tracking its properties changing.
mergeIntoObservable
If you want to merge a deep object into an observable, mergeIntoObservable
can do that and retain all of the existing observables and listeners on the way, and fire listeners as values change. This is used by persistObservable
under the hood.
trackHistory
trackHistory
creates an observable that tracks all changes in the target observable, with the previous value at the time it was changed.
Since the history is an observable you can observe it or persist it like any other observable. This can be useful for saving a version history for a text editor. If you’d like to create an undo stack, check out the undoRedo helper.
An optional second parameter lets you use an existing observable for storing the history, which can be useful to save history into an existing state object.
undoRedo
undoRedo
is similar to trackHistory in that it tracks changes to an observable. However,
undoRedo
also provides helpers for undo / redo (as the name suggests) and does the tracking for you.
An optional second parameter lets you specify how deep you’re willing to save an undo stack. By default, it will track changes forever, which means your memory will grow unbounded, so it’s recommended to set that.
When you undo, you can redo — unless you make new changes to the observable, in which case the redo stack will be removed and the new state will take its place. This is similar to how other undo/redo systems commonly work.
For convenience, we also export undos$
and redos$
which are observables that let
you track how many undos/redos you have available on the undo stack. This is especially
useful when rendering UI elements.
Hint: use batching to group sets of changes into one history state.