Developer experience: Debugging automerge documents

[CodingDive]

Hey, first of all, I'd like to thank @ept and the other contributors for this wonderful project. I've been using it for a while and am just now starting to learn more about CRDTs while accompanying my learning with Designing Data-Intensive Applications. ❤️

Is there some good information on how to debug automerge documents? I find it very difficult at times to figure out why some changes weren't applied when calling Automerge.applyChanges.

const newDocument = Automerge.applyChanges(document, lotsOfChanges);
const diff = Automerge.diff(document, newDocument); // empty diff, no changes were applied

This has happened to me a couple of times so far.

I have some ideas in mind on how the current developer experience could be improved:

• Special flag/env variable to get very verbose logging of what Automerge does behind the scenes.
• Special flag/env variable to get verbose changes when calling Automerge.getChanges, including the document (string) keys that ops.obj point to.
• Printing a warning when changes exist but aren't applied to the new document. Ideally, the warnings could hint why some changes aren't applied. Is a dependency missing? Does a conflict exist? ...
• A function for getting all the conflicts as proposed in #211.
• An event listener on the document to be notified the moment a conflict arises would potentially also be useful for debugging.
• Document best practices and tips for debugging in the readme.

[ept]

Hi @CodingDive, thanks for the feedback! Yes, I can imagine that is frustrating. Great idea to provide more visibility into what is going on inside Automerge.

How do you think the "verbose flag" should be set? An environment variable would work in Node, but not in a web browser. I'm also not sure whether it's safe to rely on console.log() existing everywhere. Maybe the best would be to pass a logging function into Automerge? By default there would be no logging, but if you pass in console.log then you'll get logs printed to the console, and if you have specialist needs (e.g. logging to a file with timestamps included), you can pass a custom logging function.

Would it be okay to pass a flag when initialising a document, e.g. Automerge.init({logger: console.log})? That logging function would then be used for all subsequent versions of that particular document.

[CodingDive]

Good idea to pass in a custom logger. Doing this upon initialization of the document would totally work for me. It might additionally need to be added to the options of Automerge.load.

[samratarmas]

+1 For Verbose Logger

[NikitaIT]

A good idea is to make the merge explicit to the user, not just to the developer. Of course, logging and debugging is important, but the code you need to debug is bad code.