add Automerge.getClock and Automerge.getMissingChanges

[josharian]

This is a new clock-based API for recording the current state of a document and then calculating changes since that state. The advantage of this API is that vector clocks are far more concise than an entire document, which makes them more suitable for persistence and network transfer.

Please review skeptically. My javascript and typescript skills are not strong.

Writing the docs made me wonder whether getMissingChanges is the right function name. It's hard to remember the difference between getChanges and getMissingChanges based on their name. Perhaps changesSince or getChangesSince might be better? Your decision; I'll implement whatever you pick.

[josharian]

Oh, and I switched the order of arguments from what we discussed on Slack. Originally it was getMissingChanges(newDoc, oldClock), but that was reversed from the order of arguments to getChanges(oldDoc, newDoc), and I thought it was better to be consistent.

[ept]

Hi @josharian, this is a great contribution, thank you! I have made a few changes in an additional commit, in particular I kept the argument order as getMissingChanges(doc, clock) rather than the other way round. I understand your reasoning for having the clock first, as it more closely mirrors the getChanges(oldDoc, newDoc), but there's already an existing backend function called getMissingChanges that puts the doc first, and I don't want to change it since that would be a breaking API change. Also, the Automerge API functions has the convention that the document is generally the first argument.

@orionz and/or @pvh, could you take a look at this? Especially @orionz as the Rust/wasm backend used to have a getClock function at some point (did it get removed again?). Do you think this is a good API to support for Automerge 1.0 going forward? Here are the docs.

[HerbCaudill]

Beat me to it! 😆 I've had this TODO in my code for over a year:

https://github.com/DevResults/cevitxe/blob/master/packages/cevitxe/src/clocks.ts#L28-L41

[ept]

@HerbCaudill By the way, I just realised that Cevitxe isn't listed as one of the data sync layers in the README. I've put a brief one-sentence description in here: 66793306c9a6d0536c086f56de4bc7d1ef8e8c84 — does this look ok? Feel free to change it to be better.

[josharian]

Thanks for doing clean-up. :)

[HerbCaudill]

@HerbCaudill By the way, I just realised that Cevitxe isn't listed as one of the data sync layers in the README. I've put a brief one-sentence description in here: 6679330 — does this look ok? Feel free to change it to be better.

I'd like to tweak the wording a bit - why don't I just make a separate PR, since it's not really related to this one.

[ept]

This PR no longer applies because it's based on the Automerge 0.x approach, so I'm closing it. The equivalent functionality is now provided by Automerge.Backend.getHeads() and Automerge.Backend.getChanges().