## Choosing a data type This is the decision that matters most, and it is worth two minutes. | Type | Concurrent edits resolve as | Reach for it when | |---|---|---| | `BcrdtText` | Both edits survive, each author's run stays contiguous | Anything a person types into at length | | `BcrdtArray` | Both insertions survive, in a stable order | Lists, ordered collections | | `BcrdtMap` | **One value wins**, deterministically but arbitrarily | Fields where a later value legitimately replaces an earlier one | | `BcrdtSet` | An add wins over a concurrent remove - if it added something (re-adding a present element is a no-op) and its entry is the one kept (concurrent adds of one element keep one entry) | Tags, membership, flags | | `BcrdtCounter` | **Every change adds up** - concurrent increments and decrements are all counted | Votes, likes, quantities, scores | | `BcrdtXmlFragment` | Children merge like array elements, attributes like map keys, text like `BcrdtText` | Structured documents - what a ProseMirror- or TipTap-style editor edits | A number in a `BcrdtMap` is a field, not a counter: two people who both read 5 and both write 6 end at 6, not 7. `BcrdtCounter` keeps each replica's changes under a key of its own, so `Add`, `Increment` and `Decrement` never conflict and the total is the sum of every replica's share - and undo takes back exactly this replica's changes: ```csharp BcrdtCounter likes = document.Map.EnsureCounter("likes"); // or document.Counter("likes") at the root likes.Increment(); long total = likes.Value; ``` A structured document - headings, paragraphs, lists, each with attributes and rich text - is a tree, and modelling it as markup in a string, or as maps of arrays, loses the merge that matters: two people editing different paragraphs, or the same one, must both keep their work. `BcrdtXmlFragment` is that tree, after Yjs's `Y.XmlFragment`: its children are `BcrdtXmlElement`s - a fixed name, attributes, children of their own - and `BcrdtXmlText`s, which are `BcrdtText` in every respect, marks included: ```csharp BcrdtXmlFragment body = document.XmlFragment("body"); // or document.Crdt.GetXmlFragment("body") var heading = new BcrdtXmlElement("h1"); // built detached, inserted in one transaction heading.SetAttribute("id", "intro"); heading.Push(new BcrdtXmlText("Hello")); body.Push(heading, new BcrdtXmlElement("p")); string markup = body.ToXmlString(); //

Hello

``` Concurrent insertions of children all survive in a stable order, edits inside one text merge character by character, and different attributes of one element never conflict; the same attribute written twice is last-writer-wins. An element's name cannot change - a paragraph that becomes a heading is a new element - and only elements and texts can be children. `ToXmlString` renders the tree escaped, attributes in ordinal order; it writes a text's characters but not its marks, which `ToDelta` reads. `Descendants()` walks the whole tree in document order. The trap is `BcrdtMap` with a long string in it. Two people editing the same field concurrently means one of them loses everything they typed - not because of a bug, but because that is what "last writer wins" means. If a field is something a human types prose into, make it a nested `BcrdtText` and both edits merge: ```csharp document.Map.EnsureText("description").Insert(0, "..."); // merges document.Map.Set("description", "..."); // one side wins ``` The same applies to `BcrdtArray.Replace` and `BcrdtArray.Move`: both are delete-then-insert. `Move` inserts a copy of the element at its new position, so a concurrent edit to the moved element is discarded - it lands on the element the move removed - and two clients moving the same element concurrently end up with two copies of it. Mutate a nested type in place instead when that matters, and when several people reorder one list - a task board, a playlist, a backlog - keep it in a `BcrdtOrderedCollection` instead of an array: a move there rewrites one field of the item rather than copying it. See [Ordering and task boards](#ordering-and-task-boards). The values a document stores are the **collaborative value model**: `null`, `bool`, `string`, integers (stored as `long`), `double`, `float`, `decimal`, `byte[]`, `DateTime`/`DateTimeOffset`, `Guid`, lists and string-keyed dictionaries of those, and nested collaborative types. Anything else is rejected up front with `NotSupportedException`, rather than becoming part of the document and making every later encode throw. Application types are flattened onto the value model through JSON with `BcrdtMap.SetObject` and read back with `Get`. ---