74 lines
12 KiB
Markdown
74 lines
12 KiB
Markdown
# @suaveplan/crdt - Conflict-free replicated data types: G-Counter, PN-Counter, OR-Set, LWW-Register, MV-Register, 2P-Set, RGA, Vector Clock, and Sync Manager
|
|
|
|
## Summary
|
|
|
|
Conflict-free Replicated Data Types (CRDTs) for distributed systems. Provides
|
|
eight composable CRDT primitives plus a vector-clock and a sync manager that
|
|
coordinate delta exchange across heterogeneous replicas.
|
|
|
|
<!-- begin:auto-docs -->
|
|
## Documentation tree
|
|
|
|
- [sync-manager](./src/core/sync-manager/sync-manager.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [sync-manager](./src/core/sync-manager/sync-manager.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [vector-clock](./src/core/vector-clock/vector-clock.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [vector-clock](./src/core/vector-clock/vector-clock.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [g-counter](./src/crdts/g-counter/g-counter.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [g-counter](./src/crdts/g-counter/g-counter.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [lww-register](./src/crdts/lww-register/lww-register.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [lww-register](./src/crdts/lww-register/lww-register.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [mv-register](./src/crdts/mv-register/mv-register.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [mv-register](./src/crdts/mv-register/mv-register.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [or-set](./src/crdts/or-set/or-set.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [or-set](./src/crdts/or-set/or-set.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [pn-counter](./src/crdts/pn-counter/pn-counter.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [pn-counter](./src/crdts/pn-counter/pn-counter.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [rga](./src/crdts/rga/rga.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [rga](./src/crdts/rga/rga.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [two-p-set](./src/crdts/two-p-set/two-p-set.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [two-p-set](./src/crdts/two-p-set/two-p-set.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [errors](./src/errors/crdt-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [crdt-error](./src/errors/crdt-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
<!-- end:auto-docs --> - [sync-manager](./src/core/sync-manager/sync-manager.md) — <!-- begin:auto-docs --> _(no submodules)_- [vector-clock](./src/core/vector-clock/vector-clock.md) — <!-- begin:auto-docs --> _(no submodules)_- [vector-clock](./src/core/vector-clock/vector-clock.md) — <!-- begin:auto-docs --> _(no submodules)_- [g-counter](./src/crdts/g-counter/g-counter.md) — <!-- begin:auto-docs --> _(no submodules)_- [g-counter](./src/crdts/g-counter/g-counter.md) — <!-- begin:auto-docs --> _(no submodules)_- [lww-register](./src/crdts/lww-register/lww-register.md) — <!-- begin:auto-docs --> _(no submodules)_- [lww-register](./src/crdts/lww-register/lww-register.md) — <!-- begin:auto-docs --> _(no submodules)_- [mv-register](./src/crdts/mv-register/mv-register.md) — <!-- begin:auto-docs --> _(no submodules)_- [mv-register](./src/crdts/mv-register/mv-register.md) — <!-- begin:auto-docs --> _(no submodules)_- [or-set](./src/crdts/or-set/or-set.md) — <!-- begin:auto-docs --> _(no submodules)_- [or-set](./src/crdts/or-set/or-set.md) — <!-- begin:auto-docs --> _(no submodules)_- [pn-counter](./src/crdts/pn-counter/pn-counter.md) — <!-- begin:auto-docs --> _(no submodules)_- [pn-counter](./src/crdts/pn-counter/pn-counter.md) — <!-- begin:auto-docs --> _(no submodules)_- [rga](./src/crdts/rga/rga.md) — <!-- begin:auto-docs --> _(no submodules)_- [rga](./src/crdts/rga/rga.md) — <!-- begin:auto-docs --> _(no submodules)_- [two-p-set](./src/crdts/two-p-set/two-p-set.md) — <!-- begin:auto-docs --> _(no submodules)_- [two-p-set](./src/crdts/two-p-set/two-p-set.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/crdt-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [crdt-error](./src/errors/crdt-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [sync-manager](./src/core/sync-manager/sync-manager.md) — <!-- begin:auto-docs --> _(no submodules)_- [vector-clock](./src/core/vector-clock/vector-clock.md) — <!-- begin:auto-docs --> _(no submodules)_- [vector-clock](./src/core/vector-clock/vector-clock.md) — <!-- begin:auto-docs --> _(no submodules)_- [g-counter](./src/crdts/g-counter/g-counter.md) — <!-- begin:auto-docs --> _(no submodules)_- [g-counter](./src/crdts/g-counter/g-counter.md) — <!-- begin:auto-docs --> _(no submodules)_- [lww-register](./src/crdts/lww-register/lww-register.md) — <!-- begin:auto-docs --> _(no submodules)_- [lww-register](./src/crdts/lww-register/lww-register.md) — <!-- begin:auto-docs --> _(no submodules)_- [mv-register](./src/crdts/mv-register/mv-register.md) — <!-- begin:auto-docs --> _(no submodules)_- [mv-register](./src/crdts/mv-register/mv-register.md) — <!-- begin:auto-docs --> _(no submodules)_- [or-set](./src/crdts/or-set/or-set.md) — <!-- begin:auto-docs --> _(no submodules)_- [or-set](./src/crdts/or-set/or-set.md) — <!-- begin:auto-docs --> _(no submodules)_- [pn-counter](./src/crdts/pn-counter/pn-counter.md) — <!-- begin:auto-docs --> _(no submodules)_- [pn-counter](./src/crdts/pn-counter/pn-counter.md) — <!-- begin:auto-docs --> _(no submodules)_- [rga](./src/crdts/rga/rga.md) — <!-- begin:auto-docs --> _(no submodules)_- [rga](./src/crdts/rga/rga.md) — <!-- begin:auto-docs --> _(no submodules)_- [two-p-set](./src/crdts/two-p-set/two-p-set.md) — <!-- begin:auto-docs --> _(no submodules)_- [two-p-set](./src/crdts/two-p-set/two-p-set.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/crdt-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [crdt-error](./src/errors/crdt-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [sync-manager](./src/core/sync-manager/sync-manager.md) — <!-- begin:auto-docs --> _(no submodules)_- [vector-clock](./src/core/vector-clock/vector-clock.md) — <!-- begin:auto-docs --> _(no submodules)_- [vector-clock](./src/core/vector-clock/vector-clock.md) — <!-- begin:auto-docs --> _(no submodules)_- [g-counter](./src/crdts/g-counter/g-counter.md) — <!-- begin:auto-docs --> _(no submodules)_- [g-counter](./src/crdts/g-counter/g-counter.md) — <!-- begin:auto-docs --> _(no submodules)_- [lww-register](./src/crdts/lww-register/lww-register.md) — <!-- begin:auto-docs --> _(no submodules)_- [lww-register](./src/crdts/lww-register/lww-register.md) — <!-- begin:auto-docs --> _(no submodules)_- [mv-register](./src/crdts/mv-register/mv-register.md) — <!-- begin:auto-docs --> _(no submodules)_- [mv-register](./src/crdts/mv-register/mv-register.md) — <!-- begin:auto-docs --> _(no submodules)_- [or-set](./src/crdts/or-set/or-set.md) — <!-- begin:auto-docs --> _(no submodules)_- [or-set](./src/crdts/or-set/or-set.md) — <!-- begin:auto-docs --> _(no submodules)_- [pn-counter](./src/crdts/pn-counter/pn-counter.md) — <!-- begin:auto-docs --> _(no submodules)_- [pn-counter](./src/crdts/pn-counter/pn-counter.md) — <!-- begin:auto-docs --> _(no submodules)_- [rga](./src/crdts/rga/rga.md) — <!-- begin:auto-docs --> _(no submodules)_- [rga](./src/crdts/rga/rga.md) — <!-- begin:auto-docs --> _(no submodules)_- [two-p-set](./src/crdts/two-p-set/two-p-set.md) — <!-- begin:auto-docs --> _(no submodules)_- [two-p-set](./src/crdts/two-p-set/two-p-set.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/crdt-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [crdt-error](./src/errors/crdt-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [sync-manager](./src/core/sync-manager/sync-manager.md) — <!-- begin:auto-docs --> _(no submodules)_- [vector-clock](./src/core/vector-clock/vector-clock.md) — <!-- begin:auto-docs --> _(no submodules)_ - [vector-clock](./src/core/vector-clock/vector-clock.md) — <!-- begin:auto-docs --> _(no submodules)_- [g-counter](./src/crdts/g-counter/g-counter.md) — <!-- begin:auto-docs --> _(no submodules)_ - [g-counter](./src/crdts/g-counter/g-counter.md) — <!-- begin:auto-docs --> _(no submodules)_- [lww-register](./src/crdts/lww-register/lww-register.md) — <!-- begin:auto-docs --> _(no submodules)_ - [lww-register](./src/crdts/lww-register/lww-register.md) — <!-- begin:auto-docs --> _(no submodules)_- [mv-register](./src/crdts/mv-register/mv-register.md) — <!-- begin:auto-docs --> _(no submodules)_ - [mv-register](./src/crdts/mv-register/mv-register.md) — <!-- begin:auto-docs --> _(no submodules)_- [or-set](./src/crdts/or-set/or-set.md) — <!-- begin:auto-docs --> _(no submodules)_ - [or-set](./src/crdts/or-set/or-set.md) — <!-- begin:auto-docs --> _(no submodules)_- [pn-counter](./src/crdts/pn-counter/pn-counter.md) — <!-- begin:auto-docs --> _(no submodules)_ - [pn-counter](./src/crdts/pn-counter/pn-counter.md) — <!-- begin:auto-docs --> _(no submodules)_- [rga](./src/crdts/rga/rga.md) — <!-- begin:auto-docs --> _(no submodules)_ - [rga](./src/crdts/rga/rga.md) — <!-- begin:auto-docs --> _(no submodules)_- [two-p-set](./src/crdts/two-p-set/two-p-set.md) — <!-- begin:auto-docs --> _(no submodules)_ - [two-p-set](./src/crdts/two-p-set/two-p-set.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/crdt-error.md) — <!-- begin:auto-docs --> _(no submodules)_ - [crdt-error](./src/errors/crdt-error.md) — <!-- begin:auto-docs --> _(no submodules)_
|
|
## Packages
|
|
|
|
| Module | Description |
|
|
|--------|-------------|
|
|
| [`GCounter`](src/crdts/g-counter/g-counter.md) | Grow-only counter — monotonically increasing per-node counters |
|
|
| [`PNCounter`](src/crdts/pn-counter/pn-counter.md) | Positive-Negative counter — bidirectional counter from two G-Counters |
|
|
| [`ORSet`](src/crdts/or-set/or-set.md) | Observe-Remove Set — concurrent add survives remove via unique tags |
|
|
| [`LWWRegister`](src/crdts/lww-register/lww-register.md) | Last-Write-Wins Register — timestamp + node-id tie-breaking |
|
|
| [`MVRegister`](src/crdts/mv-register/mv-register.md) | Multi-Value Register — preserves all concurrent writes |
|
|
| [`TwoPSet`](src/crdts/two-p-set/two-p-set.md) | Two-Phase Set — once removed, never re-added |
|
|
| [`RGA`](src/crdts/rga/rga.md) | Replicated Growable Array — ordered list with causal insert/delete |
|
|
| [`VectorClock`](src/core/vector-clock/vector-clock.md) | Causality tracking via per-node monotonic counters |
|
|
| [`CrdtSyncManager`](src/core/sync-manager/sync-manager.md) | Delta-exchange coordinator for heterogeneous CRDT collections |
|
|
|
|
## Quick Start
|
|
|
|
```ts
|
|
import { GCounter, CrdtSyncManager } from "@suaveplan/crdt";
|
|
|
|
// Simple counter
|
|
const counter = new GCounter("my-counter");
|
|
counter.increment("node-1", 3);
|
|
counter.increment("node-2", 5);
|
|
console.log(counter.total()); // 8
|
|
|
|
// Sync across replicas
|
|
const mgr = new CrdtSyncManager({ nodeId: "node-1" });
|
|
mgr.register(counter);
|
|
mgr.tick();
|
|
const deltas = mgr.exportDeltas(); // send over network
|
|
```
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
bun add @suaveplan/crdt
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|