hlc_dart 1.1.0

A Hybrid Logical Clock implementation in Dart, based on the paper "Logical Physical Clocks and Consistent Snapshots in Globally Distributed Databases".

Hybrid Logical Clock

• Hybrid Logical Clock
  • Features
  • Getting Started
  • Usage
    • Basic Usage
    • Complete Example
  • Roadmap
  • Packages

A hybrid logical clock implementation in Dart based on the paper Logical Physical Clocks and Consistent Snapshots in Globally Distributed Databases.

This library provides a Hybrid Logical Clock (HLC) implementation that combines the benefits of logical clocks and physical clocks:

• Captures causality like logical clocks (e hb f => l.e < l.f)
• Maintains closeness to physical/NTP time (l.e is close to pt.e)
• Compatible with 64-bit NTP timestamp format
• Works in peer-to-peer architectures without a central server

Features

• Local event handling
• Message exchange between peers
• Causality detection
• Serialization to/from 64-bit integers (toInt64 / fromInt64)
• Compact 8-byte big-endian binary representation (toUint8List / fromUint8List) — usable as a building block inside larger binary frames (e.g. OperationId in crdt_lf)
• Thread-safe implementation
• Zero dependencies
• Drift detection
• Mutable and immutable methods for every needed operation

Getting Started

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

dependencies:
  hlc_dart: 

Usage

Basic Usage

import 'package:hlc_dart/hlc_dart.dart';

// Create a new HLC initialized to the current time
final clock = HybridLogicalClock.now();

// Handle a local event
clock.localEvent(DateTime.now().millisecondsSinceEpoch);

// Handle receiving a message from another peer
final receivedClock = HybridLogicalClock.now();
clock.receiveEvent(DateTime.now().millisecondsSinceEpoch, receivedClock);

// Check causality
print(clock.happenedBefore(receivedClock));
print(clock.happenedAfter(receivedClock));
print(clock.isConcurrentWith(receivedClock));
print(clock >= receivedClock);
print(clock < receivedClock);

// Serialize/deserialize as a 64-bit integer
final serialized = clock.toInt64();
final deserialized = HybridLogicalClock.fromInt64(serialized);

// Or as a compact 8-byte big-endian buffer (useful when embedding an HLC
// inside a larger binary frame).
final bytes = clock.toUint8List();
final fromBytes = HybridLogicalClock.fromUint8List(bytes);

Complete Example

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.

Packages

Other bricks of the crdt "system" are:

• crdt_lf
• crdt_socket_sync
• crdt_lf_hive