crdt_lf 0.8.0

Conflict-free replicated data type (CRDT) - Local-first implementation provided in dart

CRDT LF

• CRDT LF
  • Features
  • Getting Started
  • Usage
    • Basic Usage
    • Dart Distributed Collaboration Example
    • Flutter Distributed Collaboration Example
  • Sync
  • Persistence
  • Architecture
    • CRDTDocument
    • Handlers
    • DAG
    • Change
    • Frontiers
    • Snapshot
  • Project Status
    • Roadmap
    • Contributing
  • Acknowledgments
  • Packages

A Conflict-free Replicated Data Type (CRDT) implementation in Dart. This library provides solutions for:

• Text Editing.
• List Editing.
• Text Editing with Fugue Algorithm (The Art of the Fugue: Minimizing Interleaving in Collaborative Text Editing" di Matthew Weidner e Martin Kleppmann).

Features

• ⏱️ Hybrid Logical Clock: Uses HLC for causal ordering of operations
• 🔄 Automatic Conflict Resolution: Automatically resolves conflicts in a CRDT
• 📦 Local Availability: Operations are available locally as soon as they are applied

Getting Started

Add this to your package's pubspec.yaml file:

dependencies:
  crdt_lf: ^1.0.0

Usage

Basic Usage

import 'package:crdt_lf/crdt_lf.dart';

void main() {
  // Create a new document
  final doc = CRDTDocument(
    peerId: PeerId.parse('45ee6b65-b393-40b7-9755-8b66dc7d0518'),
  );

  // Create a text handler
  final text = CRDTFugueTextHandler(doc, 'text1');

  // Insert text
  text.insert(0, 'Hello');

  // Delete text
  text.delete(0, 2); // Deletes "He"

  // Get current value
  print(text.value); // Prints "llo"
}

Dart Distributed Collaboration Example

Flutter Distributed Collaboration Example

Sync

A sync library is available in the crdt_socket_sync package. And it's used to synchronize the CRDT state between peers. More info in the README of the sync package.

A flutter example is available in the flutter_example and provide a synced version of the "Flutter Distributed Collaboration" Example.

Persistence

Persistence is not directly handled in this library but there are some out of the box solutions:

• crdt_lf_hive: adapters and utils for persist data using Hive.

Architecture

The library is built:

• above the hlc_dart package.
• around several key components:

CRDTDocument

The main document class that manages the CRDT state and handles synchronization between peers.

Handlers

Handlers are the core components of the library. They manage the state of a specific type of data and provide operations to modify it.

• CRDTFugueTextHandler: Handles text editing with the Fugue algorithm.
• CRDTListHandler: Handles list editing.
• CRDTTextHandler: Handles text editing.
• CRDTMapHandler: Handles map editing.

final doc = CRDTDocument(
  peerId: PeerId.parse('45ee6b65-b393-40b7-9755-8b66dc7d0518'),
);
final list = CRDTListHandler(doc, 'todo-list');
list.insert(0, 'Buy apples');
list.insert(1, 'Buy milk');
list.delete(0);
print(list.value); // Prints "[Buy milk]"

Every handler can be found in the handlers folder.

DAG

A Directed Acyclic Graph that maintains the causal ordering of operations.

Change

Represents a modification to the CRDT state, including operation ID, dependencies, and timestamp.

Frontiers

A structure that manages the frontiers (latest operations) of the CRDT.

Snapshot

A snapshot of the CRDT state, including the version vector and the data.

Project Status

This library is currently in progress and under active development. While all existing functionality is thoroughly tested, we are continuously working on improvements and new features.

Roadmap

A roadmap is available in the project page. The roadmap provides a high-level overview of the project's goals and the current status of the project.

Contributing

We welcome contributions! Whether you want to:

• Fix bugs
• Add new features
• Improve documentation
• Optimize performance
• Or something else

Feel free to:

1. Check out our GitHub repository
2. Look at the open issues
3. Submit a Pull Request

Acknowledgments

• Fugue Algorithm
• Hybrid Logical Clock

Packages

Other bricks of the crdt "system" are:

• hlc_dart
• crdt_socket_sync
• crdt_lf_hive