YjsSharp 26.11.8259

dotnet add package YjsSharp --version 26.11.8259
                    
NuGet\Install-Package YjsSharp -Version 26.11.8259
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="YjsSharp" Version="26.11.8259" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="YjsSharp" Version="26.11.8259" />
                    
Directory.Packages.props
<PackageReference Include="YjsSharp" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add YjsSharp --version 26.11.8259
                    
#r "nuget: YjsSharp, 26.11.8259"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package YjsSharp@26.11.8259
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=YjsSharp&version=26.11.8259
                    
Install as a Cake Addin
#tool nuget:?package=YjsSharp&version=26.11.8259
                    
Install as a Cake Tool

YjsSharp

A pure C# port of Yjs / y-crdt (yrs) for .NET: the shared CRDT types (Text, YArray, YMap, XmlFragment / XmlElement / XmlText), the binary update formats v1 and v2, state vectors, snapshots, relative positions and the undo manager, plus the y-protocols sync and awareness protocols and the y-websocket message framing.

It speaks the Yjs wire format byte for byte, so a .NET process can be a full peer of Yjs clients in the browser: hold the document on the server, persist it, edit it, and relay updates and presence between clients.

  • No native dependencies, no JavaScript engine: plain managed code targeting .NET 8 and .NET 10.
  • Wire-compatible with Yjs 13.6.x and y-protocols 1.0.x (see Compatibility).
  • MIT licensed.

Install

dotnet add package YjsSharp

Quick start

using YjsSharp;

var doc  = new Doc();
var text = doc.GetText("article");
text.Insert(0, "Hello world");
text.Format(0, 5, new Dictionary<string, object?> { ["bold"] = true });

var map = doc.GetMap("settings");
map.Set("theme", "dark");

// Send every change to the other peers.
doc.Update += (_, e) => Broadcast(e.Update);

// Apply what they send.
var other = new Doc();
other.ApplyUpdate(doc.EncodeStateAsUpdate());
Console.WriteLine(other.GetText("article").ToString());   // Hello world

// Only what the other side is missing:
var missing = doc.EncodeStateAsUpdate(other.EncodeStateVector());

// Group several changes into one transaction (and one update event).
doc.Transact(tx =>
{
    text.Insert(text.Length, "!");
    map.Delete("theme");
}, origin: "my-origin");

The static class Y mirrors Yjs' top-level functions: Y.MergeUpdates, Y.DiffUpdate, Y.EncodeStateVectorFromUpdate, Y.ConvertUpdateFormatV1ToV2 / V2ToV1, Y.Snapshot, Y.CreateDocFromSnapshot, and the v2 variants of each. Updates in format v2 go through EncodeStateAsUpdateV2 / ApplyUpdateV2 / the UpdateV2 event.

Values stored in shared types are the Yjs "Any" values - null, bool, double / long, string, byte[], IList<object?> and IDictionary<string, object?> - plus nested shared types and subdocuments (Doc). See docs/API.md for the public surface.

Working with the shared types

Values

Shared types hold the Yjs "Any" values: null, bool, numbers, string, byte[], lists (IList) and string keyed dictionaries (IDictionary<string, object?>), plus nested shared types and subdocuments. Values are encoded exactly like JavaScript would encode them (an integral number up to 2^31 as an integer, float precision when it is lossless, BigInteger as a BigInt, Undefined.Value for undefined), and decoded as long, double, string, List<object?>, Dictionary<string, object?>, byte[] and BigInteger. System.Text.Json.JsonElement values can be stored directly.

var doc  = new Doc();
var map  = doc.GetMap("settings");
var list = doc.GetArray("items");

map.Set("title", "Draft");
map.Set("limits", new Dictionary<string, object?> { ["max"] = 10, ["tags"] = new List<object?> { "a", "b" } });
list.Push(1, 2, 3);                       // three elements
list.Insert(0, new List<object?> { 0 });  // a list of elements to insert
list.Push(new object?[] { new List<object?> { 7, 8 } }); // one element that is a list

// Nested types: create them unattached, then insert them. They become live once integrated.
var todo = new YMap();
todo.Set("done", false);
list.Push(todo);
var notes = map.Set("notes", new Text("first line"));
notes.Insert(notes.Length, "\nsecond line");

Console.WriteLine(YjsSharp.Encoding.JsJson.Stringify(doc.ToJson()));

Transactions and origins

Every mutating call runs in a transaction. Without an explicit one, each call opens its own (one update event per call, like Yjs); Doc.Transact groups calls, and nested Transact calls join the outer transaction. The origin is passed to the update event, the observers (e.Transaction.Origin) and the undo manager.

doc.Transact(t =>
{
    var text = doc.GetText("body");
    text.Insert(t, 0, "Hello");                     // explicit-transaction overloads are optional
    text.Format(0, 5, new Dictionary<string, object?> { ["bold"] = true });
}, origin: "toolbar");

Observing changes

var text = doc.GetText("body");
using var sub = text.Observe(e =>
{
    foreach (var d in e.Delta)                  // Quill-style delta: insert / retain / delete with attributes
        Console.WriteLine(d);
});
using var deep = doc.GetMap("settings").ObserveDeep(events =>
{
    foreach (var e in events)                   // one event per changed type, top-level types first
        Console.WriteLine($"{string.Join("/", e.Path)}: {e.GetType().Name}");
});
doc.AfterTransaction += (_, e) => Console.WriteLine($"changed {e.Transaction.Changed.Count()} types");

ArrayEvent.Delta lists inserted elements, MapEvent.Keys (and XmlEvent.Keys for attributes) say per key whether it was added, updated or deleted with the old and new value. Observers run when the outermost transaction ends; an exception in one observer does not prevent the others or the update event, and is rethrown afterwards.

Rich text and XML

Text supports formatting attributes, embeds (InsertEmbed), ApplyDelta / ToDelta, and attributes of the type itself (SetAttribute). XmlFragment, XmlElement (node name and attributes), XmlText and XmlHook model the trees used by editors such as ProseMirror / TipTap (y-prosemirror) and render as XML strings with ToString().

History: snapshots, relative positions, undo

var doc  = new Doc(new DocOptions { GC = false });     // keep deleted content to restore snapshots
var text = doc.GetText("body");
text.Insert(0, "v1");
var snapshot = Y.Snapshot(doc);
text.Insert(2, " and v2");
var old   = Y.CreateDocFromSnapshot(doc, snapshot);    // a new Doc with the old state
var diff  = text.ToDelta(Y.Snapshot(doc), snapshot);   // changes marked with a "ychange" attribute

// A cursor that survives concurrent edits (encoded like Y.encodeRelativePosition)
var cursor = RelativePosition.FromTypeIndex(text, 2);
var bytes  = cursor.Encode();
var index  = RelativePosition.Decode(bytes).ToAbsolute(doc)?.Index;

var undo = new UndoManager(text, new UndoManagerOptions { CaptureTimeout = 500 });
text.Insert(0, "x");
undo.Undo();
undo.Redo();

Updates without a document

Y.MergeUpdates, Y.DiffUpdate, Y.EncodeStateVectorFromUpdate, Y.ParseUpdateMeta, the format conversions and Y.DecodeUpdate work on encoded updates directly, which is how a server can store and compact a document's history without loading it. Updates whose dependencies are missing are kept pending by Doc (like Yjs) and applied once the missing updates arrive; Doc.HasPendingUpdates, PendingMissing and PrunePending expose that state.

Threading

A Doc is single-writer, like the JavaScript implementation: callers must serialize access (for example one lock or one message loop per document). Starting a transaction while another thread is inside one throws ConcurrentDocumentAccessException instead of corrupting the document. Reads while another thread writes are not detected and must be avoided as well.

Differences from yrs

The core follows Yjs 13.6 wherever Yjs and yrs differ observably: updates with missing predecessors stay pending instead of being integrated behind a skip, a client id is a JavaScript-safe 32-bit number, text indices are UTF-16 code units, and InsertEmbed without attributes does not inherit surrounding formatting. yrs' move operations and weak links, which Yjs 13.6 cannot decode, are not implemented.

Sync and awareness protocols

YjsSharp.Sync implements y-protocols' sync.js and awareness.js and is byte-compatible with them:

Type Purpose
SyncProtocol Sync step 1 (state vector), sync step 2 (missing update), update messages: WriteSyncStep1, ReadSyncMessage, ...
Awareness Per-client JSON presence state with clocks, the 30 s outdated timeout and Change / Update events
AwarenessProtocol EncodeAwarenessUpdate, ApplyAwarenessUpdate, RemoveAwarenessStates, ModifyAwarenessUpdate
Messages The y-websocket framing: 0 = sync, 1 = awareness, 2 = auth, 3 = query awareness, and Handle for one frame
ProtocolMessage, SyncProtocolHandler yrs' message model and overridable protocol handler, for transports that batch messages

Awareness states are JSON text. They are normalised the way JSON.stringify(JSON.parse(text)) would, so encoded awareness updates match those of a JavaScript peer exactly. The outdated check runs on a timer of the TimeProvider given in AwarenessOptions (the system clock by default); set CheckInterval = TimeSpan.Zero and call CheckOutdated() yourself to drive it from your own loop or from a test clock.

A y-websocket compatible relay

A room holds one document and one awareness. Each connection is anything that can send a binary frame - an ASP.NET Core WebSocket, a SignalR stream, a TCP socket:

using YjsSharp;
using YjsSharp.Sync;

public sealed class Room
{
    private readonly Doc                        _doc       = new Doc();
    private readonly Awareness                  _awareness;
    private readonly HashSet<IConnection>       _conns     = new HashSet<IConnection>();
    private readonly Dictionary<IConnection, HashSet<ulong>> _clientsOf = new();

    public Room()
    {
        _awareness = new Awareness(_doc);
        _awareness.SetLocalState(null);            // the server itself has no presence

        // Every change to the document - from any connection - goes to everybody else.
        _doc.Update += (_, e) => Broadcast(Messages.EncodeUpdate(e.Update), except: e.Origin as IConnection);

        // Every awareness change goes to everybody, and we remember which clients a connection speaks for.
        _awareness.Update += (_, e) =>
        {
            if (e.Origin is IConnection conn)
            {
                var ids = _clientsOf[conn];
                foreach (var id in e.Added) ids.Add(id);
                foreach (var id in e.Removed) ids.Remove(id);
            }
            Broadcast(Messages.EncodeAwarenessUpdate(_awareness, e.All), except: null);
        };
    }

    public void OnOpen(IConnection conn)
    {
        _conns.Add(conn);
        _clientsOf[conn] = new HashSet<ulong>();
        conn.Send(Messages.EncodeSyncStep1(_doc));             // ask for what the client has
        var states = _awareness.States;
        if (states.Count > 0)
        {
            conn.Send(Messages.EncodeAwarenessUpdate(_awareness, states.Keys));
        }
    }

    public void OnMessage(IConnection conn, byte[] frame)
    {
        // Sync step 1 is answered with step 2; step 2, updates and awareness are applied with the
        // connection as origin (so the Update handlers above know where they came from).
        var reply = Messages.Handle(frame, _awareness, origin: conn);
        if (reply != null)
        {
            conn.Send(reply);
        }
    }

    public void OnClose(IConnection conn)
    {
        _conns.Remove(conn);
        AwarenessProtocol.RemoveAwarenessStates(_awareness, _clientsOf[conn], origin: null);
        _clientsOf.Remove(conn);
    }

    private void Broadcast(byte[] frame, IConnection? except)
    {
        foreach (var c in _conns)
        {
            if (c != except) c.Send(frame);
        }
    }
}

public interface IConnection
{
    void Send(byte[] frame);
}

That is the protocol y-websocket's WebsocketProvider expects: a browser client connected to this room syncs, receives everyone's edits and cursors, and gets the presence of a closed tab removed. A Doc is not thread-safe, so handle one room's messages on one thread at a time (a lock or a channel per room). To persist the room, store Y.MergeUpdates of the received updates, or _doc.EncodeStateAsUpdate(), and ApplyUpdate it when the room is created again. For a read-only connection, override SyncProtocolHandler.HandleUpdate / HandleSyncStep2, or check the frame type with Messages.ReadMessageType before handling it.

Compatibility

  • Yjs 13.6.x: updates (v1 and v2), state vectors, delete sets, snapshots and relative positions are read and written in the Yjs binary formats. The test suite replays fixtures recorded with Yjs 13.6.33 for text (with formatting, embeds, surrogate pairs and emoji), arrays, maps, nested types, XML, subdocuments, snapshots, relative positions, concurrent and out-of-order edits from several peers, garbage-collected and GC = false documents, and large documents, and checks that YjsSharp produces byte-identical encodings, merges, diffs and format conversions for the same operations.
  • y-protocols 1.0.7: sync handshakes, update messages, awareness updates and the y-websocket framing are checked against recorded byte streams.
  • A live round-trip test applies YjsSharp's updates in real Yjs and runs a seeded three-peer fuzz that alternates JavaScript and C# peers; it runs when node is available (tests/fixtures-generator), and is skipped otherwise.

Client ids are 53-bit safe like in Yjs. Text indices are UTF-16 code units, as in JavaScript.

Building and testing

dotnet build YjsSharp.slnx
dotnet run --project tests/YjsSharp.Tests                       # all tests (Microsoft.Testing.Platform)
dotnet run --project tests/YjsSharp.Tests -- --filter Awareness  # a subset

The compatibility fixtures under tests/YjsSharp.Tests/Compat/Fixtures are committed. To regenerate them, or to enable the live round-trip tests, install the pinned Yjs packages:

cd tests/fixtures-generator && npm ci && node generate.mjs

Credits

YjsSharp is a port of the work of others:

  • Yjs, y-protocols and lib0 by Kevin Jahns and contributors (MIT).
  • y-crdt / yrs, the Rust port by Bartosz Sypytkowski and contributors (MIT), whose v0.28 test suite and sync protocol implementation were ported here.
  • Ycs, an earlier C# port of Yjs (MIT), used as a reference for C# idioms.

See THIRD-PARTY-NOTICES.md for their license notices.

Maintained by Curiosity GmbH. Released under the MIT license.

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net10.0

    • No dependencies.
  • net8.0

    • No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
26.11.8259 104 11/19/2026