sdawood / atom.undo

Reactive variables with Undo-Redo

Minimalistic Undo-Redo implementation for Atoms.

Reference

Import

You must first provide an Atom implementation. You can use either

import Atom from "bacon.atom"

or

import Atom from "kefir.atom"

for example. See bacon.atom and kefir.atom for details.

It is also possible to create atoms in other ways, such as with storage, see atom.storage.

The default import

import Undo from "atom.undo"

is a function to create an undoable atom.

Undoable

To create an undoable atom, you must pass an initial value and the desired Atom constructor:

const undoable = Undo({value: initial, Atom})

The return value is a lensed atom with additional properties for controlling history.

undoable.undo() and undoable.redo()

Undoes or redoes a change (if any).

undoable.undo.count and undoable.redo.count

Observable property that gives the number of times undo or redo has an effect.

undoable.undo.has and undoable.redo.has

Observable property that gives a boolean on whether undo or redo has an effect.

undoable.initial

Observable property that gives the initial value of the undoable.

undoable.reset(value)

Resets the state of the undoable so that the given value becomes the new initial value and all history is dropped.

undoable.revert()

Resets the state of the undoable to the value of undoable.initial and drops all history.

Replace

By default, every actual change (as determined by an acyclic equality predicate) of the value of an undoable atom creates a new history entry. In many cases you don't want to generate history for every change. The Undo constructor takes an optional replace predicate as a parameter, which let's you control when the value is just replaced without creating history.

The replace function is given as a parameter an object of the form {date, value, old: {date}}, where dates have been obtained by Date.now(). If replace returns a truthy value, the latest value is replaced without creating history.

The named import Replace

import {Replace} from "atom.undo"

provides ready made replacement policies for undo.

For example, to create an undoable atom with a 2.5 second history "debounce" period, one could write:

const undoable = Undo({replace: Replace.youngerThan(2500),
                       value: initial,
                       Atom})

Replace.never

The default never policy is to never replace and always generate history.

Replace.youngerThan(periodInMilliseconds)

The youngerThan policy is to replace, without generating history, when the previous entry is younger than the given period in milliseconds.