ygo

README

Ygo

Pure-Go port of Yjs, the CRDT framework for collaborative applications, officially listed in the Yjs documentation's ports page.

Ygo speaks the Yjs V1 and V2 wire formats byte-for-byte. JavaScript clients running yjs@13.x synchronize directly with Go servers and vice versa, with both directions verified through 199 cross-language fixture scenarios generated from yjs@13.6.33. The bundled WebSocket server is Hocuspocus-compatible. No CGO; gomobile bind produces an iOS xcframework and Android AAR (manually verified, not run in CI).

Highlights

• Byte-for-byte wire compatibility, verified in both directions. 199 cross-language fixture scenarios (generated from yjs@13.6.33) cover the V1 and V2 update formats, snapshots, subdocuments, undo, relative positions, GC, awareness, and the sync protocol, JS to Go and Go to JS, plus 56 lib0 primitive vectors. The suite runs in CI on every push, so a regression in either direction fails the build.
• Pure Go, no CGO — mobile included. Cross-compiles freely to every Go target. The CRDT core, the sync client and the server also compile to js/wasm and wasip1/wasm; the one exception is the SQLite-backed store in persist/sqlite, since modernc.org/sqlite is transpiled C with no wasm target — a browser build supplies its own persist.Store instead (it is a seven-method interface). gomobile bind produces an iOS xcframework and Android AAR (manually verified on 2026-06-12, not run in CI) carrying a full mobile SDK: editable Text / Map, undo, cursors, and a built-in background sync client (WebSocket + reconnect), so a Swift / Kotlin app only renders UI. No V8, no embedded JavaScript engine, no Rust FFI bridge.
• Embeddable sync client, offline-first. The client package is a Go-native y-websocket/Hocuspocus provider: handshake, incremental updates, awareness, reconnect with backoff. With a LocalStore it persists the document to disk (pure-Go SQLite), loads it before any network so the app works offline, and syncs edits made offline up on reconnect. The building block for bots, CLI tools, server-side agents, and the mobile SDK (EnableOfflineStore).
• Complete CRDT type set. Map, Array, Text (rich-text formatting, Quill deltas, embeds), XML types, Awareness, UndoManager, Snapshots / time-travel, and Subdocuments.
• Change observers. Map.Observe / Array.Observe / Text.Observe deliver Quill-style deltas of exactly what changed; ObserveDeep bubbles events from nested types with their path. Semantic parity with yjs's YMapEvent / YArrayEvent / YTextEvent. On mobile, ObserveChanges hands a native editor the delta as JSON.
• One update per transaction. Doc.OnUpdate / OnUpdateV2 hand you each committed transaction as an update holding just its changes, the bytes yjs emits on doc.on('update') (known exceptions in the status table), with the transaction's origin; an append costs about 20 bytes however long the history. ApplyUpdateWithOrigin tags a peer's update so an echo guard and the UndoManager can tell it apart, and EncodeDiff catches a peer up from its own clock.
• Compact encoding. Commit-time block squash collapses per-character edits into single items (about 1 byte per character in V1), and garbage collection frees deleted content at commit. On a real-world editing trace V1 document size drops from ~1.97 MB to ~223 KB, competitive with V2.
• Forward-looking wire handling. ygo handles 53-bit client IDs throughout (byte-verified above 2^32), the confirmed wire-level change in the yjs@14 release candidate, and decodes Skip structs in the update stream as no-op gaps (part of the wire format since yjs v13.5). Full attribution / IdMap support waits for the v14 format to stabilize.
• Ready-to-run server: yserve. A self-hosted Yjs server in a single static binary — a Hocuspocus alternative with no Node, no Redis, no CGO. Same wire protocol, so existing @hocuspocus/provider / y-websocket clients connect unchanged; SQLite persistence and periodic document versioning built in. Also embeds as a plain http.Handler inside an existing Go backend.
• Scales horizontally. Several server instances behind a load balancer converge on the same document through a pluggable backplane: edits and live cursors both cross instances, so two users on different servers collaborate as if on one. An in-process hub ships in the core; an opt-in NATS adapter (versioned separately so the core stays dependency-free) spans machines, with a JetStream mode that resumes delivery across a broker reconnect or restart. Clustered instances share one Store and run the same ygo version.
• Federated transport over Matrix. An opt-in Matrix transport (a separate module, so mautrix stays out of a build that only wants the CRDT) turns an ordinary unencrypted Matrix room into the sync channel: peers publish updates as dev.ygo.update room events and merge what they read back, with no ygo server involved. A room is an append-only log with no ordering or exactly-once guarantee, which is exactly what Yjs updates tolerate. Room content is treated as untrusted — validated on both sides, decoded one event at a time so one bad event cannot break a whole page, encrypted rooms refused rather than silently written in the clear — though, as the module README spells out, Yjs updates do not authenticate deletes, so room membership is write access to the document. Exercised in CI against a real Dendrite on every push to main and every pull request. Its limits are documented rather than papered over.
• EU-sovereign mirror on codeberg.org/Deln0r/ygo, auto-synced from GitHub on every push for adopters who prefer or require EU-hosted code infrastructure.

Live demo: open ygo.deln0r.com in two browser tabs and start typing. Same protocol any standard Yjs ecosystem client speaks, with a pure-Go server behind it.

Quick start

package main

import (
    "fmt"

    "github.com/Deln0r/ygo"
)

func main() {
    src := ygo.NewDoc()
    m := ygo.NewMap(src, "settings")

    txn := src.WriteTxn()
    m.Set(txn, "theme", "dark")
    m.Set(txn, "lang", "go")
    txn.Commit()

    // Encode the source doc's full state as wire bytes.
    update := ygo.EncodeStateAsUpdate(src)

    // Apply to a fresh peer doc — same bytes JS Yjs's Y.applyUpdate consumes.
    dst := ygo.NewDoc()
    if err := ygo.ApplyUpdate(dst, update); err != nil {
        panic(err)
    }

    dstMap := ygo.NewMap(dst, "settings")
    fmt.Println(dstMap.Get("theme")) // dark
}

For a collaborative server backend, see yserve — a stand-alone, Hocuspocus-compatible WebSocket server with SQLite persistence and document versioning, in one static binary:

go install github.com/Deln0r/ygo/cmd/yserve@latest
yserve -addr :1234 -store data.db -version-interval 10m

Sending each change

Doc.OnUpdate hands you every committed transaction as a V1 update holding exactly that transaction's changes, the bytes of yjs's doc.on('update'), except in the three pinned cases listed in the status table below and for the Any values ygo writes differently: an object with more than one key (ygo sorts the keys, yjs keeps their insertion order) and a whole-number float64 (kept a float64, where lib0 writes a varint). Forward them to peers or append them to a log; an append costs a few bytes however long the document's history is. Apply what peers send with an origin, so the handler can tell their updates from yours:

type peer struct{ id string }
from := &peer{id: "ws-1"}

d.OnUpdate(func(update []byte, origin any) {
    if origin == from {
        return // came from that peer, do not send it back
    }
    broadcast(update)
})

err := ygo.ApplyUpdateWithOrigin(d, received, from)

OnUpdateV2 gives the V2 bytes, and ApplyUpdateV2WithOrigin applies V2 bytes with an origin. Handlers run at the end of the commit with the document lock held, in commit order; they must not open a transaction on the same document. To catch up a peer that has been away, send ygo.EncodeDiff(d, peerStateVector): it starts exactly at the peer's clock, as Y.encodeStateAsUpdate(doc, sv) does. Unlike yjs it does not append updates still waiting in the pending buffer for a missing dependency.

Undo / Redo

Wrap any shared types in an UndoManager to get scoped, grouped Undo / Redo:

d := ygo.NewDoc()
m := ygo.NewMap(d, "settings")

um := ygo.NewUndoManager(d, m) // watch m; defaults to local edits, 500ms grouping
defer um.Close()

txn := d.WriteTxn()
m.Set(txn, "theme", "dark")
txn.Commit()

um.Undo() // m no longer has "theme"
um.Redo() // "theme" == "dark" again

Only edits under the watched types made by a tracked origin are captured. The default tracks the nil origin, which local edits carry, but so does plain ApplyUpdate, exactly as in yjs: apply remote updates with ygo.ApplyUpdateWithOrigin(d, update, origin) to keep them out of the history, or track your own origin only (um.AddTrackedOrigin(mine), um.RemoveTrackedOrigin(nil)). Rapid edits inside the capture-timeout window collapse into one undo step; call um.StopCapturing() to force a boundary. The semantics match yjs@13.6.33's UndoManager, checked by cross-language conformance fixtures.

Snapshots / time-travel

Capture a point in a document's history and reconstruct it later. The source doc must have GC disabled so deleted content is retained:

d := ygo.NewDocWithOptions(ygo.Options{DisableGC: true})
txt := ygo.NewText(d, "t")

txn := d.WriteTxn()
txt.Insert(txn, 0, "world!")
txn.Commit()

snap := ygo.CreateSnapshot(d)         // mark this moment
saved := ygo.EncodeSnapshot(snap)     // persist it (byte-compatible with Y.encodeSnapshot)

txn = d.WriteTxn()
txt.Insert(txn, 0, "hello ")          // doc moves on
txn.Commit()

restored, _ := ygo.RestoreSnapshot(d, snap) // reconstruct the marked state
ygo.NewText(restored, "t").String()         // "world!"

The snapshot wire format (EncodeSnapshot / DecodeSnapshot) is byte-compatible with yjs@13.6.33's Y.encodeSnapshot, verified by cross-language fixtures including multi-client delete-set ordering. RestoreSnapshot mirrors Y.createDocFromSnapshot.

Subdocuments

Nest a Y.Doc inside a Map. The parent stores a reference (the subdoc's GUID); the subdocument's own content syncs as a separate update stream:

d := ygo.NewDoc()
m := ygo.NewMap(d, "m")

txn := d.WriteTxn()
sub := m.SetDoc(txn, "child") // nest a new subdocument
txn.Commit()

// after syncing the parent to another replica:
got, ok := m.GetDoc(d, "child") // got.GUID() == sub.GUID()

The ContentDoc wire format (GUID + options) is byte-compatible with yjs@13.6.33, verified by cross-language fixtures. Lifecycle events are observable via d.OnSubdocs (added / removed / loaded GUIDs per transaction); SetDocWithOptions(..., autoLoad) and subdoc.Load() drive the loaded set, so a sync provider knows which nested documents to fetch.

Observing changes

Subscribe to a shared type to learn exactly what changed in each transaction, local or remote:

m := ygo.NewMap(d, "settings")
unsub := m.Observe(func(e *ygo.MapEvent) {
    for key, change := range e.Keys {
        // change.Action is "add" / "update" / "delete"; change.OldValue
        // holds the prior value for update / delete.
        fmt.Printf("%s %s\n", change.Action, key)
    }
})
defer unsub()

Array.Observe and Text.Observe deliver a Quill-style delta ({Insert, Delete, Retain} ops; Text ops carry formatting attributes). Map.ObserveDeep / Array.ObserveDeep fire for changes to nested types too, with each event's Path from the observed type to the change. The event semantics match yjs's YMapEvent / YArrayEvent / YTextEvent, cross-checked against captured reference output.

Status

Feature-complete and stable. The CRDT engine, the V1 and V2 wire formats, and the full type set above are validated bidirectionally against yjs@13.6.33 and exercised in CI on every push. The public API is considered stable for the v1.x line; changes follow semantic versioning, with new functionality as minor releases and breaking changes deferred to a future major.

Layer	Status
internal/lib0 varint + RLE encoding	done; verified byte-equivalent vs JS lib0@0.2.119 (40 + 16 fixtures)
internal/block (Item, Content, Branch, Splice, Integrate-YATA, TrySquash, Repair, search markers)	done; full YATA conflict resolution + per-branch LRU position cache
internal/store (BlockStore, ItemSlice, Materialize)	done
internal/doc (Doc, Transaction, TransactionMut)	done; lock semantics + root-branch registry
internal/encoding (StateVector, IdSet, Update encode/decode/apply, Pending buffer, V1 + V2 codecs)	done; JS Yjs → Go proven by 33 V1 + 37 V2 fixture scenarios; Go → JS proven by 60 reverse fixtures (Map / Array / Text / XmlFragment)
internal/utf16 (UTF-16 length / byte-offset / surrogate-aware split)	done
internal/types/Map (Set / Get / Delete / Has / Len / Range / Clear + SetMap / SetArray / SetText)	done; nested-type construction supported
internal/types/Array (Insert / InsertRange / Push / Delete / Get / Len / Range / ToSlice + InsertMap / InsertArray / InsertText)	done; nested-type construction supported
internal/types/Text (Insert / Delete / String / Length + InsertWithAttributes / Format / InsertEmbed / Range / ToDelta / ApplyDelta)	done; full rich-text + Quill delta batch API
Nested-type construction (Map-in-Map, Array-in-Map, etc., to arbitrary depth)	done; ContentType wire format + Repair ParentID resolution + pending-queue retry
internal/types/Xml* (XmlFragment, XmlElement, XmlText)	done; ProseMirror/Tiptap/BlockNote unblocked. XmlHook (legacy) deferred.
Persistence (Store interface + modernc.org/sqlite reference impl)	done; append-only update log, Flush compaction, LoadDoc / GetStateVector / GetDiff helpers; pure-Go (no CGO). The sqlite backend runs in WAL mode with a busy timeout for concurrency-safe writes
Update-level utilities (MergeUpdates / MergeUpdatesV2 / DiffUpdate / EncodeStateVectorFromUpdate)	done; yjs-parity helpers to merge, diff, and compute a state vector from update bytes, for server-side compaction and diffing. EncodeStateVectorFromUpdate reads the bytes directly; the merge and diff helpers reconstruct a document internally. Merging preserves blocks whose causal ancestor is absent from the set, writing Skip runs for the holes exactly as yjs does, so an incomplete set is coalesced rather than silently truncated
y-sync protocol (internal/sync)	done; full Hocuspocus message subset (Sync + Awareness + QueryAwareness + Auth + Stateless + BroadcastStateless + Close + SyncStatus); per-document Auth permission scoping deferred (tech-debt)
Awareness (internal/awareness)	done; LWW presence map, JSON wire payload per y-protocols, self-eviction defense, SweepOutdated, decode caps + per-room client cap + tombstone GC (DoS hardening)
server/ (WebSocket sync server)	done; http.Handler mount-anywhere shape, per-doc broadcaster, persists every applied update to optional persist.Store. Connection lifecycle hooks (OnConnect / OnDisconnect / OnChange / OnLoadDocument / OnAuthenticate / OnStateless), read-only viewers (ReadOnly), resource caps (MaxConnsPerDoc / MaxDocs / MaxAwarenessClients), bounded broadcast writes (WriteTimeout), a Stats load snapshot, and awareness disconnect tombstones + periodic presence sweep (AwarenessTimeout)
server/backplane (multi-instance clustering)	done; pluggable pub/sub Backplane so instances behind a load balancer converge on one document, carrying both document updates and presence (relayed presence held to its own origin-partitioned share of the per-room cap, so a flood on one instance cannot starve local clients on another). In-process Memory hub in the core; the opt-in NATS adapter is a separate module (core stays dependency-free) offering core-NATS at-most-once or a JetStream mode that resumes across a broker reconnect or restart. Requires a shared Store, and all instances in a cluster must run the same version
integration/matrix (federated transport)	done; opt-in separate module carrying updates as dev.ygo.update room events over a Matrix room, no ygo server involved. Backward /messages pagination from the /sync prev_batch token (an empty page is not the end of history), per-call event-ID dedup, ygo.ValidateUpdate on both publish and read, per-event decoding so one hostile event costs one event rather than a whole page, an event-size ceiling, refusal of end-to-end-encrypted rooms, and a /messages fallback when /sync is unusable. Unit suite against a strict in-process double plus a real Dendrite in CI on every push to main and every pull request. Deliberately thin: whole blobs, no state-vector diffing, no compaction — see its README for what that costs
yserve (Hocuspocus-compat server binary)	done; single static binary with SQLite persistence (-store) and periodic document versioning (-version-interval / -keep-versions); cmd/ygo-server remains as a deprecated alias
gomobile/ (app-level mobile SDK for iOS/Android)	done; pure-Go (no CGO) bindable SDK with two levels: the full shared type set — Text (UTF-16 mutators), rich text (ApplyDelta / Format / InsertEmbed — Quill deltas in, symmetric with ObserveChanges), Map and Array (typed JSON values, nested types), and XmlFragment / XmlElement / XmlText (ProseMirror / Tiptap) — plus UndoManager (tracking the origin of a WithOrigin handle, so a collaborator's update applied with ApplyUpdateWithOrigin stays out of the user's undo), cursor anchors (relative positions), live collaborator presence (ObservePresence / PresenceStates delivering remote cursors and identity as JSON), and an embedded sync Client (NewClient / Connect / Listener) so a Swift / Kotlin app edits the Doc and renders UI while sync runs in the background; plus the bytes-in/bytes-out wire layer for custom transports, with ObserveUpdates delivering each transaction's update. gomobile bind was manually verified once (2026-06-12, Xcode 16 + NDK 27 + Go 1.26) to produce a valid Ygo.xcframework (arm64 + simulator universal) and Android .aar (arm64-v8a / armeabi-v7a / x86 / x86_64); the bind step is not run in CI (the pure-Go package compiles in CI, guarding against CGO leak). See gomobile/README.md for commands.
V2 update encoding	done; lib0 RLE primitives + column encoder/decoder + Update.{EncodeV2,DecodeV2} + public ygo.{EncodeStateAsUpdateV2,EncodeDiffV2,ApplyUpdateV2}; bidirectional cross-language fixtures vs yjs@13.6.33
Untrusted-input hardening	done; every wire-supplied element count in the V1/V2 update, snapshot, id-set, and Any-content decoders is bounded against the input length, closing a length-prefix amplification DoS (a few bytes forcing a multi-terabyte allocation). Continuous fuzzing of the decode + apply paths runs nightly in CI (fuzz.yml) with the discovered crashers committed as regression corpus
dmonad/crdt-benchmarks B1-B4 port	done; B1.1-B1.11 / B2.1-B2.4 / B3.1+3+4 / B4 (260k-edit real-world LaTeX trace). Baseline in BENCHMARKS.md.
UndoManager (internal/undo)	done; scoped Undo / Redo over Map / Array / Text with capture-timeout grouping, tracked-origin filtering (AddTrackedOrigin / RemoveTrackedOrigin), and a Redone chain for deletion restore. Cross-language conformance vs yjs@13.6.33 (27 scenarios). Deleting a nested shared type is not yet undoable: its contents are not restored
Per-transaction updates (Doc.OnUpdate / OnUpdateV2, ApplyUpdateWithOrigin)	done; the yjs update / updateV2 events, emitted after GC with the transaction's origin (byte for byte apart from the pinned cases here and the Any values ygo writes differently: multi-key objects, whose keys it sorts, and whole-number float64s); EncodeDiff / EncodeDiffV2 cut the first block at the remote clock as yjs does, but leave out the pending buffer, which yjs appends. 34 cross-language scenarios, 5 pinned divergences (deleting a nested type lists only the type in the delete set; no rich-text cleanup transaction after concurrent formatting; undo restores kept tombstones as separate structs)
Snapshots (CreateSnapshot / EncodeSnapshot / RestoreSnapshot)	done; V1 wire format byte-compatible with yjs@13.6.33 (cross-language fixtures incl. multi-client), RestoreSnapshot mirrors Y.createDocFromSnapshot
Subdocuments (Map.SetDoc / Map.GetDoc)	done; ContentDoc wire format (GUID + options) byte-compatible with yjs@13.6.33, cross-language fixtures. Lifecycle events via OnSubdocs / autoLoad / Load
Wire client-ID width	53-bit client IDs throughout (uint64 + varint), byte-verified against yjs@13.6.33 for IDs above 2^32. Forward-compatible with the wider client-ID space yjs@14 introduces
Commit-time block squash	done; merges same-client adjacent-clock items at commit (~1 byte/char V1), paired with Apply-side partial-overlap slicing for correct remote integration of merged blocks
GC merging	done; deleted content is freed at commit (ContentDeleted, byte-aligned with yjs) and adjacent deleted runs are merged. Deleting a nested shared type recursively collapses its whole subtree into garbage-collected runs (cross-language fixtures), matching yjs. Skipped when GC is disabled or for items an UndoManager keeps
Relative positions (cursors)	done; CreateRelativePositionFromTypeIndex / CreateAbsolutePositionFromRelativePosition, binary form byte-compatible with Y.encodeRelativePosition, follows undone deletions; cross-language fixtures incl. surrogate pairs and 53-bit client IDs
Versioned persistence	done; named point-in-time versions independent of the live log (persist.VersionStore: save / list / load / restore / prune), atomic restore, sqlite reference implementation
Change observers	done; Map.Observe (YMapEvent: add / update / delete + oldValue), Array.Observe and Text.Observe (Quill-style insert / delete / retain delta, Text formatting-aware), Map/Array.ObserveDeep (event-path bubbling from nested types). Deltas cross-checked against captured yjs@13.6.33 output; fire on local and remote transactions, in first-change order, with one deep call per transaction, checked against yjs by 19 observer scenarios. gomobile Text/Map.ObserveChanges deliver the delta as Quill JSON

Goals

1. Binary protocol compatibility with Yjs v13.x in both V1 and V2 wire formats. Byte-for-byte. JS clients sync with Go servers and vice versa, bidirectionally verified.
2. Idiomatic Go API. Channels for events, explicit transactions, error returns.
3. Pure Go. No CGO. gomobile bind works for iOS/Android.
4. Pluggable persistence with modernc.org/sqlite reference implementation.
5. Performance within 2× of yrs on dmonad/crdt-benchmarks B1-B4. See BENCHMARKS.md.

Non-goals

• C-FFI surface. Yrs already provides this; Ygo's unique value is pure-Go native binaries.
• Drop-in replacement for the Node.js Yjs runtime. Ygo is the Go port; use yjs itself if you want a JavaScript runtime.
• Loro, Automerge, RGA, or other CRDT designs. Ygo implements the Yjs wire format, period.

Wire compatibility

The single most-important guarantee of this project is byte-level wire compatibility with yjs@13.x. This is enforced by 199 cross-language fixture scenarios (plus 56 lib0 primitive vectors):

• 33 V1 forward fixtures (testdata/yjs-updates.json) — JS Yjs encodes via Y.encodeStateAsUpdate, Go decodes and applies, state matches.
• 37 V2 forward fixtures (testdata/yjs-update-v2-fixtures.json) — same with Y.encodeStateAsUpdateV2.
• 60 reverse fixtures (testdata/go-updates.json + go-update-v2-fixtures.json) — Go encodes via EncodeStateAsUpdate / EncodeStateAsUpdateV2, JS Yjs decodes via Y.applyUpdate / Y.applyUpdateV2, state matches.
• 69 feature fixtures — XML (5), awareness (6), sync protocol (6), undo (27), snapshots (4), subdocuments (3), wire edge cases incl. 53-bit client IDs (3), nested-type GC (4), relative positions (11), all captured from the pinned JS reference and byte-compared in both directions where the feature has a Go encoder.

Three more fixture sets compare behaviour and bytes with yjs but stay out of these totals while any of their scenarios is a pinned divergence: per-transaction updates and diffs (34 scenarios, every OnUpdate / OnUpdateV2 event and EncodeDiff / EncodeDiffV2 against state vectors that end inside a block; 5 pinned), rich text (35; 8 pinned) and observers (19; 1 pinned). Each pin is listed with its cause in the test and fails the build when the behaviour changes, in either direction.

The fixtures regenerate from pinned yjs@13.6.33 + lib0@0.2.119 + y-protocols@1.0.7 on every CI run; git diff --exit-code testdata/ catches byte-level regressions.

How is this different from Hocuspocus / y-websocket / y-leveldb?

Project	Runtime	What it provides	Relationship to Ygo
yjs (npm)	Node / browser	The reference CRDT implementation	Ygo's wire-format target
y-websocket	Node	Reference WebSocket server	yserve is a Go-native equivalent
Hocuspocus	Node	Production WebSocket server with auth, persistence, extensions	yserve speaks the same 8-message envelope (Sync / Awareness / QueryAwareness / Auth / Stateless / BroadcastStateless / Close / SyncStatus) in one static binary
yrs	Rust	Reference Rust port	Ygo's executable spec for porting decisions
y-leveldb, y-indexeddb	Node / browser	Persistence backends	Ygo's persist/sqlite is a Go-native equivalent
Ygo	Go	CRDT engine + WS server + persistence in one monorepo, pure-Go for native mobile	This project

If you have an existing Yjs deployment and want to move the server side to Go (no Node runtime, single static binary, native iOS / Android via gomobile) — Ygo is the path. If you're starting fresh and your team is comfortable with Node, Hocuspocus is the mature choice.

Benchmarks

See BENCHMARKS.md for the full table. Highlights from B4 (259,778-edit real-world LaTeX paper trace) on Apple M3, Go 1.26:

Metric	Ygo V1	Ygo V2	yjs (Node, Intel i5-8400)	ywasm (Intel i5-8400)
Apply all edits	20.3 s	20.3 s	5.7 s	28.7 s
Encoded doc size	223 KB	160 KB	160 KB	160 KB
Encode time	0.6 ms	10.5 ms	11 ms	3 ms
Parse time	4.4 ms	4.5 ms	39 ms	16 ms

How to read this:

• Doc sizes are now at or near yjs parity. V1 lands within 1.4× of yjs (223 KB vs 160 KB; it was 1.97 MB, ~12× bloat, before commit-time block squash + GC shipped). V2 matches yjs byte-for-byte-scale at 160 KB. A 2,000-character sequential insert encodes to ~1.0 byte/char in V1. Squash ships with the paired Apply-side partial-overlap handling that keeps remote integration correct when a peer sends a merged block overlapping the receiver's state.
• Apply throughput is the trade. ~3.5× yjs wall-clock on different hardware (Apple M3 vs the slower i5-8400, so the normalized gap is wider): the per-commit squash + GC scans that buy the 8.8× smaller documents roughly doubled apply time versus the pre-squash build. Against yrs's published sub-10-s B4 numbers this sits at about 2×, at the DESIGN.md target boundary, with known commit-pipeline optimization headroom. (ywasm is yrs compiled to WebAssembly and is not representative of native yrs — wasm overhead inflates it ~5×.)
• Encode and parse are fast once the doc is compact: V1 encode 0.6 ms and parse 4.4 ms on the 223 KB document, both ahead of yjs's published numbers on its hardware.

A direct head-to-head harness against native yrs under identical hardware is on the roadmap but not yet run; the numbers above are honest absolute figures with hardware caveats.

Roadmap

Shipped since v1.0 (June 2026): a full Hocuspocus-compatible sync server (connection lifecycle hooks, read-only viewers, resource caps, a stats snapshot), horizontal scaling across instances with cross-cluster cursors, an offline-first Go client, WAL-backed SQLite persistence, continuous fuzzing, the yjs update-level utilities, and per-transaction update events with origins (1.22.0). See the CHANGELOG, the releases, and examples/.

Open: a documentation site, an external security audit, and yjs v14 wire features (attribution / IdMap) once v14 reaches GA.

Per-layer port notes live in docs/yrs-port-notes/. Items intentionally deferred or partial are tracked in docs/tech-debt.md. Detailed design decisions in DESIGN.md.

Examples

Runnable examples in examples/:

• collab-server — embed the WebSocket sync server and wire its hooks (OnConnect, ReadOnly, OnChange, OnLoadDocument), resource caps, a SQLite store, and a /stats endpoint.
• collab-client — a Go-native sync client: connect, observe remote changes, edit, converge.
• offline-first — client-side offline persistence with a LocalStore: usable with no network, edits survive restarts and sync up on reconnect.

The core CRDT API also has output-verified runnable examples on pkg.go.dev (Map, Array, Text, two-document sync, per-transaction updates, UndoManager).

Documentation

• DESIGN.md — project design document
• CHANGELOG.md — release history, with an upgrade-impact note on every release that changes what a running deployment does
• BENCHMARKS.md — performance baseline + B1-B4 methodology
• gomobile/README.md — iOS xcframework + Android AAR build instructions
• docs/yrs-port-notes/ — per-layer port notes describing how each yrs subsystem maps to Go
• integration/matrix/README.md — the Matrix transport: wire format, what is measured against a real homeserver, and its limits
• docs/tech-debt.md — deferred work and known limitations
• CONTRIBUTING.md — DCO sign-off, no CLA

License

MIT. See LICENSE.

Acknowledgements

• Kevin Jahns (dmonad) for Yjs and the YATA algorithm.
• Bartosz Sypytkowski for yrs and the architecture deep dive.

Documentation

Overview

Package ygo is a pure-Go port of the Yjs CRDT framework.

ygo is binary-protocol compatible with the npm yjs package (V1 update encoding), allowing JavaScript clients to synchronize seamlessly with Go servers and vice versa.

Pure-Go means no CGO, so gomobile bind works for iOS/Android targets.

The public API is stable for the v1.x line: new functionality lands as a minor release and breaking changes are deferred to a future major, per semantic versioning. The wire formats are validated bidirectionally against yjs on every push.

See https://github.com/Deln0r/ygo for documentation and examples.

Example

Example is the basic shape: create a document, edit a shared type inside a write transaction, and read the value back.

package main

import (
	"fmt"

	"github.com/Deln0r/ygo"
)

func main() {
	doc := ygo.NewDoc()
	settings := ygo.NewMap(doc, "settings")

	txn := doc.WriteTxn()
	settings.Set(txn, "theme", "dark")
	settings.Set(txn, "fontSize", int64(14))
	txn.Commit()

	fmt.Println(settings.Get("theme"))
	fmt.Println(settings.Get("fontSize"))
}

Output:
dark
14

Example (Array)

Example_array shows the shared Array: an ordered sequence you append to and read positionally.

package main

import (
	"fmt"

	"github.com/Deln0r/ygo"
)

func main() {
	doc := ygo.NewDoc()
	todo := ygo.NewArray(doc, "todo")

	txn := doc.WriteTxn()
	todo.Push(txn, "buy milk", "write code")
	txn.Commit()

	fmt.Println(todo.Len())
	fmt.Println(todo.Get(0))
	fmt.Println(todo.Get(1))
}

Output:
2
buy milk
write code

Example (Sync)

Example_sync shows the core CRDT property: two documents that never talked to each other each apply the other's update and converge on the same merged state, independent of order.

package main

import (
	"fmt"

	"github.com/Deln0r/ygo"
)

func main() {
	// Peer A sets a title on its copy.
	a := ygo.NewDoc()
	am := ygo.NewMap(a, "doc")
	wa := a.WriteTxn()
	am.Set(wa, "title", "Hello")
	wa.Commit()

	// Peer B sets a different key on its own copy.
	b := ygo.NewDoc()
	bm := ygo.NewMap(b, "doc")
	wb := b.WriteTxn()
	bm.Set(wb, "author", "Ada")
	wb.Commit()

	// Exchange full-state updates and apply each to the other.
	if err := ygo.ApplyUpdate(a, ygo.EncodeStateAsUpdate(b)); err != nil {
		panic(err)
	}
	if err := ygo.ApplyUpdate(b, ygo.EncodeStateAsUpdate(a)); err != nil {
		panic(err)
	}

	// Both converge to the same merged state.
	fmt.Println(am.Get("title"), am.Get("author"))
	fmt.Println(bm.Get("title"), bm.Get("author"))
}

Output:
Hello Ada
Hello Ada

Example (Text)

Example_text shows the shared Text: a collaborative string edited by index. Inserts commute so concurrent edits converge.

package main

import (
	"fmt"

	"github.com/Deln0r/ygo"
)

func main() {
	doc := ygo.NewDoc()
	note := ygo.NewText(doc, "note")

	txn := doc.WriteTxn()
	_ = note.Insert(txn, 0, "world")
	_ = note.Insert(txn, 0, "hello ")
	txn.Commit()

	fmt.Println(note.String())
}

Output:
hello world

Example (Undo)

Example_undo shows the built-in UndoManager: track a shared type, edit it, then step backward and forward through the edit history.

package main

import (
	"fmt"

	"github.com/Deln0r/ygo"
)

func main() {
	doc := ygo.NewDoc()
	m := ygo.NewMap(doc, "doc")
	undo := ygo.NewUndoManager(doc, m)

	txn := doc.WriteTxn()
	m.Set(txn, "title", "draft")
	txn.Commit()
	fmt.Println(m.Get("title"))

	undo.Undo()
	fmt.Println(m.Has("title"))

	undo.Redo()
	fmt.Println(m.Get("title"))
}

Output:
draft
false
draft

Example (Updates)

Example_updates shows Doc.OnUpdate: every committed transaction arrives as one update holding just that transaction's changes, the bytes yjs emits on doc.on('update'). A sync provider forwards its own and skips what a peer sent, which it recognises by the origin it applied it with.

package main

import (
	"fmt"

	"github.com/Deln0r/ygo"
)

func main() {
	type peer struct{ name string }
	remote := &peer{name: "ws-1"}

	d := ygo.NewDoc()
	text := ygo.NewText(d, "notes")
	var outgoing [][]byte
	d.OnUpdate(func(update []byte, origin any) {
		if origin == remote {
			return // came from that peer, do not send it back
		}
		outgoing = append(outgoing, update)
	})

	for _, s := range []string{"hello", " world"} {
		txn := d.WriteTxn()
		if err := text.Insert(txn, text.Length(), s); err != nil {
			panic(err)
		}
		txn.Commit()
	}

	// The peer replays what was sent, then appends "!" itself.
	p := ygo.NewDoc()
	pt := ygo.NewText(p, "notes")
	for _, u := range outgoing {
		if err := ygo.ApplyUpdate(p, u); err != nil {
			panic(err)
		}
	}
	since := ygo.EncodeStateVector(p)
	txn := p.WriteTxn()
	if err := pt.Insert(txn, pt.Length(), "!"); err != nil {
		panic(err)
	}
	txn.Commit()
	fromPeer, err := ygo.EncodeDiff(p, since)
	if err != nil {
		panic(err)
	}
	if err := ygo.ApplyUpdateWithOrigin(d, fromPeer, remote); err != nil {
		panic(err)
	}

	fmt.Println(len(outgoing), "updates sent")
	fmt.Println(text.String())
}

Output:
2 updates sent
hello world!

Index

• Constants
• Variables
• func ApplyUpdate(d *Doc, raw []byte) error
• func ApplyUpdateV2(d *Doc, raw []byte) error
• func ApplyUpdateV2WithOrigin(d *Doc, raw []byte, origin any) error
• func ApplyUpdateWithOrigin(d *Doc, raw []byte, origin any) error
• func DiffUpdate(update, remoteSV []byte) ([]byte, error)
• func EncodeDiff(d *Doc, remoteSVBytes []byte) ([]byte, error)
• func EncodeDiffV2(d *Doc, remoteSVBytes []byte) ([]byte, error)
• func EncodeRelativePosition(rpos RelativePosition) ([]byte, error)
• func EncodeSnapshot(s Snapshot) []byte
• func EncodeStateAsUpdate(d *Doc) []byte
• func EncodeStateAsUpdateV2(d *Doc) []byte
• func EncodeStateVector(d *Doc) []byte
• func EncodeStateVectorFromUpdate(update []byte) ([]byte, error)
• func EqualSnapshots(a, b Snapshot) bool
• func HasPending(d *Doc) bool
• func MergeUpdates(updates [][]byte) ([]byte, error)
• func MergeUpdatesV2(updates [][]byte) ([]byte, error)
• func MissingSV(d *Doc) []byte
• func ValidateUpdate(raw []byte) error
• type AbsolutePosition
  • func CreateAbsolutePositionFromRelativePosition(d *Doc, rpos RelativePosition) (AbsolutePosition, bool)
• type Array
  • func NewArray(d *Doc, name string) *Array
• type ArrayDeltaOp
• type ArrayEvent
• type Attrs
• type Awareness
  • func NewAwareness(clientID uint64) *Awareness
• type Branch
• type ChunkKind
• type DeltaOp
• type Doc
  • func NewDoc() *Doc
  • func NewDocWithOptions(opts Options) *Doc
  • func RestoreSnapshot(d *Doc, snap Snapshot) (*Doc, error)
• type KeyChange
• type Map
  • func NewMap(d *Doc, name string) *Map
• type MapEvent
• type Options
• type RelativePosition
  • func CreateRelativePositionFromTypeIndex(t SharedType, index uint64, assoc int64) (RelativePosition, error)
  • func DecodeRelativePosition(buf []byte) (RelativePosition, error)
• type SharedType
• type Snapshot
  • func CreateSnapshot(d *Doc) Snapshot
  • func DecodeSnapshot(buf []byte) (Snapshot, error)
• type SubdocsEvent
• type Text
  • func NewText(d *Doc, name string) *Text
• type TextEvent
• type Transaction
• type TransactionMut
• type UndoManager
  • func NewUndoManager(d *Doc, scope ...UndoScope) *UndoManager
  • func NewUndoManagerWithOptions(d *Doc, opts UndoManagerOptions, scope ...UndoScope) *UndoManager
• type UndoManagerOptions
• type UndoScope
• type XmlElement
  • func NewXmlElement(d *Doc, name string) *XmlElement
• type XmlFragment
  • func NewXmlFragment(d *Doc, name string) *XmlFragment
• type XmlText
  • func NewXmlText(d *Doc, name string) *XmlText

Examples

• Package
• Package (Array)
• Package (Sync)
• Package (Text)
• Package (Undo)
• Package (Updates)

Constants

const (
	ChunkString = types.ChunkString
	ChunkEmbed  = types.ChunkEmbed
)

Text.Range emits chunks of either of these kinds.

const DefaultAwarenessTimeout = awareness.DefaultTimeout

DefaultAwarenessTimeout is the y-protocols convention for stale awareness-entry eviction (30 seconds). Pass to Awareness.SweepOutdated.

const MaxClientID = doc.MaxClientID

MaxClientID is the upper bound on Doc.ClientID values (2^53 - 1, matching JS Yjs's safe-integer range).

const Version = "1.23.0"

Version is the ygo release this source tree corresponds to. It is set as part of the release ceremony, so a checkout of main between releases carries the last released value.

Variables

var ErrSnapshotGC = errors.New("ygo: RestoreSnapshot requires the source Doc to have GC disabled (NewDocWithOptions with DisableGC: true)")

ErrSnapshotGC is returned by RestoreSnapshot when the source Doc has garbage collection enabled, which can discard content a snapshot needs to reconstruct.

Functions

func ApplyUpdate

func ApplyUpdate(d *Doc, raw []byte) error

ApplyUpdate decodes raw and integrates it into d. Items whose dependencies the local store has not yet seen - an unseen Origin, RightOrigin or Parent, or a gap in the item's own client clock - queue in the per-doc pending buffer and drain automatically on subsequent ApplyUpdate calls that satisfy them.

It decodes ONE update and ignores any bytes after it, so a buffer holding two appended updates applies only the first and loses the second with no error (yjs behaves identically). Run ValidateUpdate first on anything you did not encode yourself.

Use HasPending / MissingSV to inspect the queue.

func ApplyUpdateV2

func ApplyUpdateV2(d *Doc, raw []byte) error

ApplyUpdateV2 decodes V2 wire bytes and integrates them into d. Pending-buffer semantics identical to ApplyUpdate (V1) — items missing causal dependencies queue silently and drain on subsequent ApplyUpdate / ApplyUpdateV2 calls.

Same trailing-byte behaviour as ApplyUpdate: one update is read and the rest of the buffer is ignored. There is no strict validator for V2 bytes, because the V2 decoder does not report a remainder - so for V2 the check has to be "I encoded this myself".

V1 and V2 are NOT wire-interchangeable, and the two mistakes fail differently. ApplyUpdateV2 on V1 bytes errors loudly. ApplyUpdate on V2 bytes does NOT: the V1 decoder reads the V2 prefix as a complete, empty update and returns nil, so the call is a silent no-op (measured). There is no autodetect; the caller must know which version they have via the surrounding transport metadata.

func ApplyUpdateV2WithOrigin

func ApplyUpdateV2WithOrigin(d *Doc, raw []byte, origin any) error

ApplyUpdateV2WithOrigin is ApplyUpdateV2 with origin as the transaction's Origin; see ApplyUpdateWithOrigin.

func ApplyUpdateWithOrigin

func ApplyUpdateWithOrigin(d *Doc, raw []byte, origin any) error

ApplyUpdateWithOrigin is ApplyUpdate with origin as the transaction's Origin, the third argument of yjs Y.applyUpdate. Observers, OnUpdate handlers and UndoManager origin filters see it, which is how a sync provider keeps from sending a peer's update back out:

d.OnUpdate(func(update []byte, origin any) {
	if origin != peer {
		broadcast(update)
	}
})
err := ygo.ApplyUpdateWithOrigin(d, fromPeer, peer)

origin must be a comparable value (a string, a pointer, a struct of comparable fields) if an UndoManager tracks origins by it.

func DiffUpdate

func DiffUpdate(update, remoteSV []byte) ([]byte, error)

DiffUpdate returns the part of a V1 update that a peer identified by remoteSV (a wire-encoded state vector, e.g. from EncodeStateVector or EncodeStateVectorFromUpdate) is missing. Mirrors yjs diffUpdate: trim a stored update before sending it to a peer that already has part of it.

It reconstructs the update's state and diffs against remoteSV, cutting the first block of each client at the remote clock like EncodeDiff. The update is integrated first, so blocks commit-time squash can merge come out merged, where yjs diffUpdate keeps the input's blocks. Blocks whose dependencies are absent from the input are DROPPED rather than carried: unlike MergeUpdates, this does not preserve the pending buffer. That is fine for the intended use - trimming a self-contained update before sending it - and lossy for anything else, including the output of MergeUpdates over an incomplete set, which by design can contain blocks that do not integrate on their own. Do not use DiffUpdate to re-trim such an update.

func EncodeDiff

func EncodeDiff(d *Doc, remoteSVBytes []byte) ([]byte, error)

EncodeDiff returns the wire-encoded V1 update covering the blocks d has that the remote (per remoteSVBytes) does not. A nil remoteSVBytes is treated as the empty SV — emit everything. Each client's first block is cut at the remote's clock, so the bytes are those of Y.encodeStateAsUpdate(doc, sv), except that yjs also appends updates its pending buffer holds; the delete set is the whole document's, as there. For one transaction's changes alone, use Doc.OnUpdate.

remoteSVBytes is the V1 wire-encoded form of the remote's state vector (the same shape EncodeStateVector produces).

func EncodeDiffV2

func EncodeDiffV2(d *Doc, remoteSVBytes []byte) ([]byte, error)

EncodeDiffV2 is the V2 analogue of EncodeDiff. State-vector argument shape is identical (still V1 wire-encoded SV); only the outgoing update bytes use the V2 column layout.

func EncodeRelativePosition

func EncodeRelativePosition(rpos RelativePosition) ([]byte, error)

EncodeRelativePosition serialises rpos to the yjs binary form (byte-compatible with Y.encodeRelativePosition). Errors only on a zero-value rpos with no anchor set.

func EncodeSnapshot

func EncodeSnapshot(s Snapshot) []byte

EncodeSnapshot returns the V1 wire encoding of s, byte-compatible with yjs `Y.encodeSnapshot`.

func EncodeStateAsUpdate

func EncodeStateAsUpdate(d *Doc) []byte

EncodeStateAsUpdate returns the wire-encoded V1 update carrying the doc's full state. Apply to a fresh peer doc to bring it up to speed in one shot; same bytes interoperate with JS Yjs's Y.encodeStateAsUpdate.

func EncodeStateAsUpdateV2

func EncodeStateAsUpdateV2(d *Doc) []byte

EncodeStateAsUpdateV2 returns the wire-encoded V2 update carrying the doc's full state. V2 is the column-oriented alternative wire format used by Y.encodeStateAsUpdateV2 / Hocuspocus-V2 paths and some adopters' on-disk persistence layers (y-leveldb, y-indexeddb, SQLite/Postgres Hocuspocus adapters).

V1 and V2 are NOT wire-interchangeable — see ApplyUpdateV2.

func EncodeStateVector

func EncodeStateVector(d *Doc) []byte

EncodeStateVector returns the wire-encoded V1 state vector of d. Sync-protocol callers send this to peers as "here's what I have; send me everything else."

func EncodeStateVectorFromUpdate

func EncodeStateVectorFromUpdate(update []byte) ([]byte, error)

EncodeStateVectorFromUpdate computes the state vector a V1 update advances to, directly from the update bytes without reconstructing a document. Mirrors yjs encodeStateVectorFromUpdate: index or diff stored updates server-side without loading the full document into memory.

func EqualSnapshots

func EqualSnapshots(a, b Snapshot) bool

EqualSnapshots reports whether two snapshots are identical.

func HasPending

func HasPending(d *Doc) bool

HasPending reports whether d has any queued items awaiting causal dependencies.

func MergeUpdates

func MergeUpdates(updates [][]byte) ([]byte, error)

MergeUpdates coalesces V1 update blobs into a single equivalent V1 update. Returns nil for an empty input - nil is not itself a valid update, so guard the length before feeding the result onward.

Nothing is dropped. A block whose causal dependencies are absent from the merged set is preserved, and the clocks nobody supplied come out as Skip runs, which is how the wire format expresses a hole and what yjs mergeUpdates emits for the same input. Two consequences worth knowing: the output may contain Skip runs where an ordinary update would not, and applying it to an empty document may leave part of it queued in the pending buffer until the missing history arrives. Carrying is not integrating.

Used by persistence layers for compaction (Flush) and by transports that want to batch-coalesce updates before sending.

func MergeUpdatesV2

func MergeUpdatesV2(updates [][]byte) ([]byte, error)

MergeUpdatesV2 is the V2 counterpart of MergeUpdates, with the same contract: nothing is dropped, holes come out as Skip runs, and the result may not integrate fully into an empty document until the missing history arrives. Returns nil for an empty input.

The two formats carry a Skip's length differently - V2 puts it in the rest stream rather than the len column - so the emitters are separate code paths with separate tests.

func MissingSV

func MissingSV(d *Doc) []byte

MissingSV returns the wire-encoded V1 state vector identifying the clocks d needs to receive in order to drain its pending buffer. An empty result means the queue is empty.

Sync-protocol callers send this to peers as a re-fetch request: "I am stuck on items that need updates past this clock."

func ValidateUpdate

func ValidateUpdate(raw []byte) error

ValidateUpdate returns an error unless raw is a well-formed V1 update that is consumed in its entirety, WITHOUT integrating it into any document. Use it on updates that arrive from somewhere you do not control.

It is stricter than ApplyUpdate in the one way that matters for untrusted input: ApplyUpdate decodes a single update and silently ignores whatever bytes follow it. So `append(a, b...)` applies only a, loses b, and reports no error anywhere - the reference implementation (yjs 13.6.32, measured) behaves the same, which is why ApplyUpdate keeps that behaviour and this separate check exists. Combine updates with MergeUpdates, never with append. Note the boundary: MergeUpdates returns nil for an empty batch, and nil is not a valid update, so guard the length before validating.

Validating costs a decode, not an integrate: it does not build a document or run conflict resolution. It does allocate in proportion to the input, so a network-facing caller should bound the payload size before calling rather than treating this as a free filter on unbounded bytes.

V1 only. The V2 decoder does not report a trailing remainder, so there is no equivalent strict check for V2 bytes; passing V2 bytes here is reported as such rather than misdiagnosed.

Types

type AbsolutePosition

type AbsolutePosition = types.AbsolutePosition

AbsolutePosition is a resolved RelativePosition: the shared type's branch and the current numeric index within it.

func CreateAbsolutePositionFromRelativePosition

func CreateAbsolutePositionFromRelativePosition(d *Doc, rpos RelativePosition) (AbsolutePosition, bool)

CreateAbsolutePositionFromRelativePosition resolves rpos against the current state of d. ok is false when the anchor refers to state this replica has not yet seen or to a garbage-collected range.

Acquires the doc's locks internally; calling it while holding an open Transaction / TransactionMut on the same doc from the same goroutine deadlocks (Go RWMutex is not re-entrant).

type Array

type Array = types.Array

Shared-type wrappers — re-exported from internal/types.

func NewArray

func NewArray(d *Doc, name string) *Array

type ArrayDeltaOp

type ArrayDeltaOp = types.ArrayDeltaOp

ArrayDeltaOp is one op of an array change delta: exactly one of Insert (values), Delete (count), or Retain (count) is set.

type ArrayEvent

type ArrayEvent = types.ArrayEvent

ArrayEvent is delivered to Array observers (Array.Observe) after a transaction that changed the array. Delta is the Quill-style change description. Semantic parity with yjs YArrayEvent.

type Attrs

type Attrs = types.Attrs

Attrs is the format-attribute map used by Text's rich-text API and DeltaOp. Keys are arbitrary strings; values are JSON-serializable scalars. A nil value clears the attribute on the affected range.

type Awareness

type Awareness = awareness.Awareness

Awareness tracks per-client ephemeral state (cursors, names, selections). Independent of any Doc; the local clientID is passed at construction. Embedders typically pair an Awareness with a Doc and use d.ClientID() as the awareness clientID.

func NewAwareness

func NewAwareness(clientID uint64) *Awareness

NewAwareness returns a fresh Awareness for the given local clientID. Use d.ClientID() to keep the awareness layer in sync with the doc.

type Branch

type Branch = block.Branch

Branch is the low-level shared-data container the types layer wraps. Most callers should use the typed constructors (NewMap, NewArray, NewText, NewXmlFragment) rather than building Branches directly. Re-exported here for advanced cases (custom shared-type implementations, observability code).

type ChunkKind

type ChunkKind = types.ChunkKind

ChunkKind discriminates the variants emitted by Text.Range.

type DeltaOp

type DeltaOp = types.DeltaOp

DeltaOp is one Quill-style delta operation produced by Text.ToDelta and (future) consumed by Text.ApplyDelta.

type Doc

type Doc = doc.Doc

Doc is a single CRDT replica — the local view of a collaborative document. Construct with NewDoc; mutate via WriteTxn; read via ReadTxn. See the doc-comment on the underlying type for the full concurrency contract.

func NewDoc

func NewDoc() *Doc

NewDoc returns a fresh Doc with default options and a random client identifier.

func NewDocWithOptions

func NewDocWithOptions(opts Options) *Doc

NewDocWithOptions returns a fresh Doc with the given options.

func RestoreSnapshot

func RestoreSnapshot(d *Doc, snap Snapshot) (*Doc, error)

RestoreSnapshot reconstructs the document state that d had at the moment snap was taken, returning it as a new Doc. Byte-equivalent to yjs `Y.createDocFromSnapshot`.

d must have been created with GC disabled (ygo.NewDocWithOptions with DisableGC: true); otherwise deleted content the snapshot references may have been collected and RestoreSnapshot returns ErrSnapshotGC. The returned Doc also has GC disabled so it can itself be snapshotted.

The source Doc is not logically changed (the reconstruction may split blocks internally, which is transparent to readers).

type KeyChange

type KeyChange = types.KeyChange

KeyChange describes one map key's change in a MapEvent: Action is "add", "update", or "delete"; OldValue is the prior value (nil for "add").

type Map

type Map = types.Map

Shared-type wrappers — re-exported from internal/types.

func NewMap

func NewMap(d *Doc, name string) *Map

NewMap, NewArray, NewText, NewXmlFragment return wrappers bound to the root branch with the given name in d. The branch is lazily created on first call; subsequent calls with the same name return wrappers pointing at the same underlying state.

Per-branch type discipline: a branch should be used as ONE type (Map OR Array OR Text OR XML). Mixing types on the same root branch produces undefined behaviour.

Call these before opening a transaction, not inside one. They take the document lock, which an open WriteTxn on the same document already holds, so a call inside the transaction blocks forever. yjs allows getMap inside transact; this port does not yet.

type MapEvent

type MapEvent = types.MapEvent

MapEvent is delivered to Map observers (Map.Observe) after a transaction that changed the map, describing which keys changed and how. Byte-for-byte semantic parity with yjs YMapEvent.

type Options

type Options = doc.Options

Options bundles per-Doc settings (deterministic ClientID, GC disable). The zero value is the recommended configuration.

type RelativePosition

type RelativePosition = types.RelativePosition

RelativePosition is a cursor/selection anchor attached to the document model rather than a numeric index, so it stays on the same logical character as concurrent edits land. Create one with CreateRelativePositionFromTypeIndex, ship it between peers with EncodeRelativePosition (byte-compatible with Y.encodeRelativePosition), and resolve it back to an index with CreateAbsolutePositionFromRelativePosition.

func CreateRelativePositionFromTypeIndex

func CreateRelativePositionFromTypeIndex(t SharedType, index uint64, assoc int64) (RelativePosition, error)

CreateRelativePositionFromTypeIndex anchors index within the shared type t (any wrapper: Map, Array, Text, Xml*). index counts UTF-16 code units for Text, elements for Array. assoc >= 0 sticks to the character after the position (default for cursors), assoc < 0 to the character before it.

func DecodeRelativePosition

func DecodeRelativePosition(buf []byte) (RelativePosition, error)

DecodeRelativePosition parses the yjs binary form.

type SharedType

type SharedType = UndoScope

SharedType is any shared-type wrapper (Map, Array, Text, XmlFragment, XmlElement, XmlText). Alias of UndoScope; both name the same one-method interface.

type Snapshot

type Snapshot = encoding.Snapshot

Snapshot is a point-in-time marker of a document's history (the deleted ID ranges plus per-client clock heads as of the snapshot). Encode it with EncodeSnapshot for storage; reconstruct the document state it captured with RestoreSnapshot (see the Snapshot doc).

For time-travel to work, create the doc with GC disabled (ygo.NewDocWithOptions with DisableGC) so deleted content the snapshot references is retained.

func CreateSnapshot

func CreateSnapshot(d *Doc) Snapshot

CreateSnapshot captures the current state of d as a Snapshot. Byte-compatible with yjs `Y.snapshot(doc)`.

func DecodeSnapshot

func DecodeSnapshot(buf []byte) (Snapshot, error)

DecodeSnapshot parses a V1 snapshot produced by EncodeSnapshot or yjs `Y.encodeSnapshot`.

type SubdocsEvent

type SubdocsEvent = doc.SubdocsEvent

SubdocsEvent carries the subdocument lifecycle changes of one transaction: GUIDs added, removed, and loaded. Observe with Doc.OnSubdocs.

type Text

type Text = types.Text

Shared-type wrappers — re-exported from internal/types.

func NewText

func NewText(d *Doc, name string) *Text

type TextEvent

type TextEvent = types.TextEvent

TextEvent is delivered to Text observers (Text.Observe) after a transaction that changed the text. Delta is the formatting-aware Quill-style change description. Semantic parity with yjs YTextEvent.

type Transaction

type Transaction = doc.Transaction

Transaction is a read-only transaction holding the doc's read lock for its lifetime. Created by Doc.ReadTxn; released by Close.

type TransactionMut

type TransactionMut = doc.TransactionMut

TransactionMut is a write transaction holding the doc's write lock. Created by Doc.WriteTxn; released by Commit.

type UndoManager

type UndoManager = undo.UndoManager

UndoManager records local mutations under a scope of shared types and reverses them with Undo / Redo. It subscribes to the doc's transaction lifecycle; close it with Close when no longer needed.

Scope is given as the typed wrappers themselves (a Map, Array, Text, or XML type). Only mutations under one of the scoped types, made by a tracked origin, are captured. The default tracks the nil origin: local edits made without one, but also updates applied with plain ApplyUpdate, exactly as yjs does. Apply a peer's updates with ApplyUpdateWithOrigin to keep them out of the history, or track only your own origin (AddTrackedOrigin, RemoveTrackedOrigin(nil)). Bursty edits within the capture-timeout window collapse into a single undo step.

m := ygo.NewMap(d, "settings")
um := ygo.NewUndoManager(d, m)
defer um.Close()
// ... edits to m ...
um.Undo() // reverts the last captured step

func NewUndoManager

func NewUndoManager(d *Doc, scope ...UndoScope) *UndoManager

NewUndoManager creates an UndoManager on d watching the given scope of shared types. At least one scope type is required.

um := ygo.NewUndoManager(d, myMap, myArray)

func NewUndoManagerWithOptions

func NewUndoManagerWithOptions(d *Doc, opts UndoManagerOptions, scope ...UndoScope) *UndoManager

NewUndoManagerWithOptions is NewUndoManager with explicit options.

type UndoManagerOptions

type UndoManagerOptions = undo.Options

UndoManagerOptions configures an UndoManager. A zero value selects the defaults: 500 ms capture timeout, track the nil origin only.

type UndoScope

type UndoScope interface {
	Branch() *Branch
}

UndoScope is anything an UndoManager can watch. Every shared-type wrapper (Map, Array, Text, XmlFragment, XmlElement, XmlText) satisfies it via its Branch method.

type XmlElement

type XmlElement = types.XmlElement

Shared-type wrappers — re-exported from internal/types.

func NewXmlElement

func NewXmlElement(d *Doc, name string) *XmlElement

NewXmlElement wraps a branch as an XmlElement. Typically used for root-level XML where the branch was constructed via d.Branch(name); nested elements should be constructed via XmlFragment.InsertXmlElement / XmlElement.InsertXmlElement which set TypeRef and Name automatically.

type XmlFragment

type XmlFragment = types.XmlFragment

Shared-type wrappers — re-exported from internal/types.

func NewXmlFragment

func NewXmlFragment(d *Doc, name string) *XmlFragment

type XmlText

type XmlText = types.XmlText

Shared-type wrappers — re-exported from internal/types.

func NewXmlText

func NewXmlText(d *Doc, name string) *XmlText