Lattice

This documents Lattice, for more comprehensive documentation on lattices refer to swindon documentation.

API

class Lattice({onUpdate})

Create a new lattice. A Lattice instance can be used before connection is established so it isn’t created attached to a connection.

To attach the lattice to a connection Guard.lattice() (see stateful api):

let lat = new Lattice()
// ...
swindon.guard()
 .init(...)
 .lattice('example-org', 'chat-rooms:', lat)

Because we explicitly support optimistic updates, you can use lattice object before connection is updated or even Swindon object is created.

onUpdate(updated_keys, lattice)

The function called when update is received. The updated_keys is a array of key names updated. And the lattice is this object.

The pseudo code handling updates is like this:

for(let key of updated_keys) {
  let read_messages = lattice.getCounter(key, 'read_messages')
  let total_messages = lattice.getCounter(key, 'total_messages')
  setUnreadNumber(key, total_messages - read_messages)
}

getCounter(key, variable)

Returns value of counter CRDT (variable name has _counter suffix stripped).

updateCounter(key, variable, new_value)

Update internal state of a counter CRDT (variable name has _counter suffix stripped). Returns true if value really changed.

See update notes.

getSet(key, variable)

Returns value of set CRDT (variable has _set suffix stripped).

updateSet(key, variable, additional_set)

Update internal state of a set CRDT (variable name has _set suffix stripped). Returns true if value really changed.

See update notes.

getRegister(key, variable)

Returns value of register CRDT (variable name has _register suffix stripped). The value is a tuple [stamp, value], not just value.

updateRegister(key, variable[, new_stamp, new_value])

Update internal state of a register CRDT (variable name has _register suffix stripped). Returns true if value really changed.

See update notes.

allKeys()

Iterator over all keys of the lattice (with registered prefix stripped).

Update Notes

All update* methods do domain specific update procedure. I.e. if you pass smaller value to updateCounter it will be ignored.

Also this API doesn’t ensure that corresponding value is updated at the server side. It’s application responsibility to call needed application-specific server-side method that updates value in the database.

All update methods throw InvalidType when type of the value does not match expected one.

Warning

Currently there is no way to undo optimistic transaction, we will add some API to support this use case in future.