automerge

Overview ¶

Package automerge provides the ability to interact with automerge documents. It is a featureful wrapper around automerge-rs that uses cgo to avoid reimplementing the core engine from scratch.

Document Structure and Types ¶

Automerge documents have a JSON-like structure, they consist of a root map which has string keys, and values of any supported types.

Supported types include several immutable primitive types:

• bool
• string, []byte
• float64, int64, uint64
• time.Time (in millisecond precision)
• nil (untyped)

And four mutable automerge types:

• Map - a mutable map[string]any
• List - a mutable []any
• Text – a mutable string
• Counter – an int64 that is incremented (instead of overwritten) by collaborators

If you read part of the doc that has no value set, automerge-go will return a Value with Kind() == KindVoid. You cannot create such a Value directly or write one to the document.

On write automerge-go will attempt to convert provided values to the most appropriate type, and error if that is not possible. For example structs are maps are converted to *Map, slices and arrays to *List, most numeric types are converted to float64 (the default number type for automerge), with the exception of int64 and uint64.

On read automerge-go will return a *Value, and you can use As to convert this to a more useful type.

Interacting with the Document ¶

Depending on your use-case there are a few ways to interact with the document, the recommended approach for reading is to cast the document to a go value:

doc, err := automerge.Load(bytes)
if err != nil { return err }

myVal, err := automerge.As[*myType](doc.Root())
if err != nil { return err }

If you wish to modify the document, or access just a subset, use a Path:

err := doc.Path("x", "y", 0).Set(&myStruct{Header: "h"})
v, err := automerge.As[*myStruct](doc.Path("x", "y", 0).Get())

It is always recommended to write the smallest change to the document, as this will improve the experience of other collaborative editors.

Writing to a path will create any intermediate Map or List objects needed, Reading from a path will not, but may return a void Value if the intermediate objects don't exist.

The automerge mutable types have additional methods. You can access these methods by calling Path.Map, Path.List, Path.Text or Path.Counter which assume the path is of the type you say it is:

values, err := doc.Path("collection").Map().Values()
fmt.Println(values)

When you do this, any errors caused by traversing the path will be returned from methods called on the returned objects.

Controling formatting of structs ¶

By default automerge will convert your struct to a map. For each public field in the struct (the name starts with an uppercase letter) automerge will add an entry to the map with the name of the field and the fields value converted to an automerge value recursively.

You can control this behaviour using struct tags:

struct Example {
	Renamed bool `automerge:"newname"`
	Private bool `automerge:"-"`
}

If the tag is present and equal to "-" the field will be ignored by automerge, otherwise the fields name will be set to the value of the tag.

Syncing and concurrency ¶

You can access methods on *Doc from multiple goroutines and access is mediated appropriately. For other types, you must provide your own syncronization, or only use them from one goroutine at a time.

If you retain a Map, List, Counter, or Text object while the document is being modified concurrently be aware that its value may change, or it may be deleted from the document. A safer pattern is to fork the document, make the changes you want, and then merge your changes back into the shared document.

There are a few different ways to keep distributed automerge docs in sync. If you're mostly making changes in one place and syncing them to another, you can use Doc.SaveIncremental and Doc.LoadIncremental

//* process 1 *
initBytes, err := doc.Save()
for {
	// ... make changes ...
	bytes, err := doc.SaveIncremental()
	ch <- bytes
}

//* process 2*
err := automerge.Load(initBytes)
for bytes := range ch {
	err := doc.LoadIncremental(bytes)
}

If both peers are making changes you can use a SyncState object to keep them in sync. This wraps an underlying efficient sync protocol to minimize both round-trips and bandwidth used.

//* process 1 *
syncState := automerge.NewSyncState(doc)
for {
	m, valid := syncState.GenerateMessage()
	if valid {
		sendCh <- m.Bytes()
	}

	msg := <-recvCh
	_, err := syncState.ReceiveMessage(msg)
	if err != nil {
		panic(err)
	}
}

//* process 2 *
syncState := automerge.NewSyncState(doc)
for {
	msg := <-sendCh
	_, err := syncState.ReceiveMessage(msg)
	if err != nil {
		panic(err)
	}

	m, valid := syncState.GenerateMessage()
	if valid {
		recvCh <- m.Bytes()
	}
}

If you need more flexibility, you can use Doc.Changes and Doc.Apply to manually track the changes you want to transfer. This puts more burden on the implementor to ensure an absense of bugs.

//* process 1 *
heads := doc.Heads()
for {
	// ... make changes ...
	changes, err := doc.Changes(heads)
	heads = doc.Heads()
	bytes := changes.Save()
	ch <- bytes
}

//* process 2 *
for bytes := range ch {
	changes, err := automerge.LoadChanges(bytes)
	err := doc.Apply(changes)
}