Y-Go: A Yjs-Compatible CRDT Implementation in Go

Y-Go is a high-performance, Yjs-compatible implementation of the YATA CRDT algorithm in pure Go. It provides binary-level compatibility with Yjs, enabling seamless interoperability between Go services and JavaScript applications.

Features

• ✅ Yjs Binary Protocol Compatibility

  • Update encoding/decoding (V1 and V2)
  • State vector encoding/decoding
  • Sync protocol message encoding
  • Awareness protocol support

• ✅ Core CRDT Data Types

  • YText: Collaborative text editing with rich formatting
  • YArray: Collaborative arrays
  • YMap: Collaborative key-value maps
  • YDoc: Document container

• ✅ YATA Algorithm

  • Conflict-free replicated data types
  • Strong eventual consistency
  • Efficient garbage collection

• ✅ Testing Infrastructure

  • Optional JavaScript runtime integration (goja) for running Yjs test suite
  • Interoperability tests with Yjs
  • Fuzzing support

Architecture

This project follows a modular architecture inspired by y-octo:

y-go/
├── pkg/                    # Public API
│   └── ygo/               # Main package
├── internal/              # Private implementation
│   ├── encoding/          # Binary protocol encoding/decoding
│   ├── types/             # CRDT data types (Text, Array, Map)
│   ├── algorithm/         # YATA algorithm implementation
│   └── utils/             # Utilities
├── tests/                 # Test utilities
│   ├── js/               # JavaScript test runner (optional)
│   └── vectors/          # Test vectors for interoperability
└── examples/              # Usage examples

Project Goals

1. 100% Protocol Compatibility: Every update generated by Y-Go must be accepted by Yjs, and vice versa
2. Performance: Optimized for high-throughput scenarios
3. Safety: No undefined behavior, memory-safe Go implementation
4. Testability: Comprehensive test suite with Yjs interoperability verification

Installation

go get github.com/coreseekdev/y-go

Quick Start

package main

import (
    "fmt"
    "github.com/coreseekdev/y-go/pkg/ygo"
)

func main() {
    // Create a new document
    doc := ygo.NewDoc()
    doc.SetClientID(1)

    // Get a text type
    text := doc.GetText("test")

    // Insert text
    text.Insert(0, "Hello, World!")

    // Encode state as update
    update := doc.EncodeStateAsUpdate()

    // On another machine/client
    doc2 := ygo.NewDoc()
    doc2.ApplyUpdate(update)

    // Both have the same content
    fmt.Println(text.String()) // "Hello, World!"
}

Testing

Run Go Tests

go test ./...

Run Yjs Test Suite (Optional)

The project includes an optional JavaScript runtime integration to run Yjs test suite:

# Install with JS test support
go test -tags js_tests ./tests/js/...

# This will:
# 1. Download and setup Yjs test framework
# 2. Run all Yjs tests against Y-Go implementation
# 3. Verify binary-level compatibility

Generate Test Vectors

# Generate test vectors from Yjs
cd tests/js
node generate-vectors.js

Development Status

• Project structure
• Binary encoding/decoding
• Core data structures (ID, Item, StructStore)
• YATA algorithm
• YText implementation
• YArray implementation
• YMap implementation
• YDoc implementation
• Update encoding V1
• Update encoding V2
• State vector
• DeleteSet
• Sync protocol
• JS test runner
• Interoperability tests

Contributing

Contributions are welcome! Please ensure:

1. All tests pass: go test ./...
2. Code is properly formatted: go fmt ./...
3. JS interoperability tests pass (when applicable)
4. No new lint warnings

License

MIT License - See LICENSE file for details

Acknowledgments

• Yjs - Original JavaScript implementation
• y-octo - Architecture inspiration
• y-crdt - Protocol reference