@groundstate

All-in-one local-first data toolkit -- combines CRDTs, sync, storage, and conflict resolution in a single package.

Installation

# npm
npm install @groundstate

# yarn
yarn add @groundstate

# pnpm
pnpm add @groundstate

Quick Start

import {
  Doc, Field, Counter, List,
  SyncEngine, WebSocketTransport,
  PersistenceEngine, IndexedDBAdapter,
} from '@groundstate';

// Define your document
const todo = Doc({
  title: Field(''),
  done: Field(false),
  votes: Counter(0),
  tags: List<string>(),
});

// Persist locally
const persistence = new PersistenceEngine(todo, {
  adapter: new IndexedDBAdapter('my-app'),
  autoSave: true,
});
await persistence.load();

// Sync with peers
const sync = new SyncEngine(todo, new WebSocketTransport('wss://sync.example.com'));
await sync.start();

What's Included

This package re-exports everything from the core Groundstate packages:

• @groundstate/crdt -- Schema-defined CRDTs (LWWRegister, PNCounter, RGAList, LWWMap, PeriText)
• @groundstate/sync -- Sync engine with WebSocket, WebRTC, HTTP, BLE, and filesystem transports
• @groundstate/store -- Persistence with IndexedDB, SQLite, encryption, migrations, and queries
• @groundstate/resolve -- Conflict detection and resolution strategies

Additional Exports

• createSnapshot / encodeSnapshot / decodeSnapshot -- Document snapshots
• snapshotToURL / snapshotFromURL -- Encode snapshots as shareable URLs

CLI

npx groundstate <command>

The groundstate CLI is included for project scaffolding and management tasks.

API Highlights

See the individual package READMEs for detailed API documentation:

• @groundstate/crdt -- Clock, CRDT types, schema, encoding, history, GC, relations
• @groundstate/sync -- Protocol, transports, presence, auth, ACL
• @groundstate/store -- Adapters, persistence, encryption, compaction, migrations, query, backup
• @groundstate/resolve -- Detection, strategies, policies, visualization, audit

Documentation

See the full documentation for complete API reference.

License

MIT