Function changeAt

Make a change to the document as it was at a particular point in history

Remarks

This function is similar to change but allows you to make changes to the document as if it were at a particular point in time. To understand this imagine a document created with the following history:

let doc = automerge.from({..})
doc = automerge.change(doc, () => {...})

const heads = automerge.getHeads(doc)

// fork the document make a change
let fork = automerge.fork(doc)
fork = automerge.change(fork, () => {...})
const headsOnFork = automerge.getHeads(fork)

// make a change on the original doc
doc = automerge.change(doc, () => {...})
const headsOnOriginal = automerge.getHeads(doc)

// now merge the changes back to the original document
doc = automerge.merge(doc, fork)

// The heads of the document will now be (headsOnFork, headsOnOriginal)

ChangeAt produces an equivalent history, but without having to create a fork of the document. In particular the newHeads field of the returned ChangeAtResult will be the same as headsOnFork.

Why would you want this? It's typically used in conjunction with diff to reconcile state which is managed concurrently with the document. For example, if you have a text editor component which the user is modifying and you can't send the changes to the document synchronously you might follow a workflow like this:

• On initialization save the current heads of the document in the text editor state
• Every time the user makes a change record the change in the text editor state

Now from time to time reconcile the editor state and the document

• Load the last saved heads from the text editor state, call them oldHeads
• Apply all the unreconciled changes to the document using changeAt(doc, oldHeads, ...)
• Get the diff from the resulting document to the current document using diff passing the ChangeAtResult.newHeads as the before argument and the heads of the entire document as the after argument.
• Apply the diff to the text editor state
• Save the current heads of the document in the text editor state