@groundstate/crdt

Schema-defined CRDTs with full TypeScript inference for building local-first applications.

Installation

# npm
npm install @groundstate/crdt

# yarn
yarn add @groundstate/crdt

# pnpm
pnpm add @groundstate/crdt

Quick Start

import { Doc, Field, Counter, List, HLC } from '@groundstate/crdt';

// Define a schema-driven CRDT document
const todo = Doc({
  title: Field(''),
  done: Field(false),
  priority: Counter(0),
  tags: List<string>(),
});

// Mutate with automatic conflict-free merging
todo.title = 'Buy groceries';
todo.priority.increment(1);
todo.tags.push('shopping');

// Merge changes from another peer
const remoteTodo = Doc({ title: Field(''), done: Field(false), priority: Counter(0), tags: List<string>() });
remoteTodo.title = 'Buy groceries and snacks';
todo.merge(remoteTodo);

API Highlights

Clock

• HLC -- Hybrid Logical Clock for causally ordered timestamps
• HLCTimestamp -- Timestamp type used across all CRDT operations

CRDT Types

• LWWRegister -- Last-writer-wins register for single values
• PNCounter -- Positive-negative counter supporting increment/decrement
• RGAList -- Replicated growable array for ordered collections
• LWWMap -- Last-writer-wins map for key-value data
• PeriText -- Rich-text CRDT with inline formatting marks

Schema

• Doc / Document -- Create typed CRDT documents from a schema definition
• DocFactory -- Factory for producing documents with a shared schema
• Field / Counter / List -- Schema field builders

Encoding

• BinaryEncoder / BinaryDecoder -- Compact binary serialization
• encodeDocument / decodeDocument -- Full document serialization
• LazyDocument -- Decode documents on demand for large datasets

History & Diffing

• OpLog -- Append-only operation log
• UndoManager -- Undo/redo support for local changes
• diff / applyPatches -- Compute and apply structural diffs

Garbage Collection

• GarbageCollector -- Reclaim memory from tombstoned operations
• collectableTombstones / gcList / gcMap -- Fine-grained GC helpers

Relations

• RefManager -- Manage document-to-document references with cascade/nullify delete semantics

Documentation

See the full documentation for complete API reference.

License

MIT