convergent 0.1.0

Lightweight, composable CRDTs for decentralized systems
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

# convergent

[![CI](https://github.com/MaloWinrhy/convergent/actions/workflows/ci.yml/badge.svg)](https://github.com/MaloWinrhy/convergent/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Lightweight, composable CRDTs (Conflict-Free Replicated Data Types) for decentralized systems.

CRDTs are data structures that can be replicated across nodes, modified independently, and merged with a **mathematically guaranteed consistent result** — no central coordination required.

## Types

| Type | Description | Use case |
|------|-------------|----------|
| `GCounter` | Grow-only counter | View counts, event tracking |
| `PNCounter` | Positive-Negative counter | Likes/dislikes, stock levels |
| `LWWRegister` | Last-Writer-Wins register | User profile fields, settings |
| `ORSet` | Observed-Remove set | Shopping carts, tag lists |

## Usage
```toml
[dependencies]
convergent = "0.1"
```
```rust
use convergent::{GCounter, Merge};

let mut node_a = GCounter::new("a");
let mut node_b = GCounter::new("b");

node_a.increment(3);
node_b.increment(5);

node_a.merge(&node_b);
assert_eq!(node_a.value(), 8);
```

## Design

Every type implements the `Merge` trait, which guarantees:

- **Commutative** — `a.merge(b) == b.merge(a)`
- **Associative** — `a.merge(b).merge(c) == a.merge(b.merge(c))`
- **Idempotent** — `a.merge(a) == a`

The `LWWRegister` uses [`hlc_id`](https://github.com/MaloWinrhy/hlc_id) for causally-ordered timestamps, connecting this crate to the broader problem of time in distributed systems.

## Related

- [`hlc_id`](https://github.com/MaloWinrhy/hlc_id) — Hybrid Logical Clock IDs (used by `LWWRegister`)
- [A comprehensive study of CRDTs](https://hal.inria.fr/inria-00555588) — Shapiro et al., 2011

## License

MIT