An immutable, conflict-free replicated game tree data type.
Use npm to install:
$ npm install @sabaki/crdt-gametree
const GameTree =let tree1 =let tree2 =let newTree1 = tree1let newTree2 = tree2let mergedTree1 = newTree1let mergedTree2 = newTree2console// => trueconsole// => true
This library is based upon and is completely compatible with @sabaki/immutable-gametree. Nearly all properties, functions, and behavior that @sabaki/immutable-gametree exports you can expect in this library as well.
We will only point out subtle differences and additional functions in this document. Please consult the @sabaki/immutable-gametree documentation for a full overview of the functionalities.
A node is represented by an object of the following form:
id: <Primitive>data:property: <String>: <Array<Primitive>> | <Array<CollaborativeText>>parentId: <Primitive> | nullchildren: <Array<NodeObject>>
Note that a so-called collaborative text property can contain a non-primitive value. To get the string value from a
CollaborativeText, simply call the instance function
toString(). The class
CollaborativeText serializes into a JSON string, so calling
JSON.stringify on node objects will still work.
Collaborative Text Properties
Adding and removing values to or from properties are merged when happening simultaneously. However, if you have a property that only has a single value and needs to be replaced, the update will follow the "winner takes it all" strategy.
That means if two users update a single property value simultaneously, only the changes of one user will be reflected in the game tree eventually. The changes of the other user will be discarded.
To allow collaborative editing for certain cases, you can specify certain properties as collaborative text properties. These properties can only contain one value, a
CollaborativeText class which contains the string.
Updates to a collaborative text property made by multiple users will be merged consistently in the end.
Every mutation operation made to a game tree draft will be represented by a change object:
id: <Primitive>operation: <String>args: <Array>retauthor: <Primitive>timestamp: <Number>
id contains a unique change id while
author contains the
GameTree id that made the change.
<Primitive>(optional) - A unique author id. Default: A random UUID
<Array<String>>(optional) - An array of property identifiers that are collaborative text properties
- See @sabaki/immutable-gametree
<Function>(optional) - If you specify this function, you have to make sure it generates globally unique ids, not just locally unique ones.
<Primitive> - The unique author id.
<Number> - Current logical timestamp.
<Array<String>> - An array of property identifiers that are collaborative text properties. This property will be inherited to all mutations.
A generator function that yields all changes made to the tree since initialization in reverse order.
Returns an array of change objects that consists of all the changes made to the tree since initialization in logical order.
Returns the id of the change that led to the current tree state.
Compares the history of
oldTree and returns an array of changes that are missing in
tree in logical order.
oldTree defaults to the game tree we mutated from.
Returns a new
GameTree instance that applies the given
changes to the current
Returns a new
GameTree instance that represents the tree state at the change in the history of
tree with the given
changeId is not given, it returns a new
GameTree instance that represents the tree state at the very beginning of the tree history.
This operation does not destroy the previous history.
- Functions prefixed with
UNSAFE_will throw errors.
removeFromPropertywill throw errors for collaborative text properties.
<Primitive> - The
GameTree id on which the draft is based on.
<Number> - The current logical timestamp.
draft.updateCollaborativeTextProperty(id, property, change)
<Object> | <String>
Updates the collaborative text property of the node with the given
id according to a collaborative text change object
change of the following structure:
deletions: <Array<Number>>insertions: <Array<at: <Number>insert: <String>>>
For example, applying the following collaborative text change object to
deletions: 11 6insertions:at: 12insert: ". How are you?"at: 6insert: "cruel w"
will result in
"Hello cruel world. How are you?". If you specify a string as
change, we will perform a diff between the old string and the new one, and automatically generate a minimal collaborative text change object for you in the background.
- immutable-gametree - An immutable game tree data type.