@thi.ng/vclock

[!NOTE] This is one of 199 standalone projects, maintained as part of the @thi.ng/umbrella monorepo and anti-framework.

🚀 Please help me to work full-time on these projects by sponsoring me on GitHub. Thank you! ❤️

• About
• Status
• Installation
• Dependencies
• API
• Authors
• License

About

Vector clock functions for synchronizing distributed states & processes.

Vector clock algorithm:

• Initially all clocks are zero.
• Each time a process experiences an internal event, it increments its own logical clock in the vector by one (inc()).
• Each time a process sends a message, it increments its own logical clock in the vector by one and then sends a copy of its own vector.
• Each time a process receives a message, it increments its own logical clock in the vector by one and updates each element in its vector by taking the maximum of the value in its own vector clock and the value in the vector in the received message (merge()).

The package provides the following immutable vector clock operations, where vector clocks are plain JS objects:

• inc(clock, id) - increment (or create) clock component
• remove(clock, id) - remove clock component
• merge(a, b) - merge two vector clocks
• signedSkew(a, b) - max signed difference between vector clocks
• absSkew(a, b) - max unsigned difference between vector clocks
• compare(a, b) - comparator for logically ordering vector clocks
• isBefore(a, b) - true if a < b
• isAfter(a, b) - true if a > b
• isConcurrent(a, b) - if both clocks represent concurrent updates
• equiv(a, b) - equality predicate
• orderAsc(a, b) - alias for compare()
• orderDesc(a, b) - reverse order to orderAsc()

References:

• Wikipedia
• Princeton COS 418: Distributed Systems
  • Lecture 4
  • Lecture 5
• F. Mattern: Virtual Time and Global States of Distributed Systems
• P. Krzyzanowski: Clock synchronization
• L. Lamport
• Akka docs

Status

BETA - possibly breaking changes forthcoming

Search or submit any issues for this package

Installation

yarn add @thi.ng/vclock

ESM import:

import * as vc from "@thi.ng/vclock";

Browser ESM import:

<script type="module" src="https://esm.run/@thi.ng/vclock"></script>

JSDelivr documentation

For Node.js REPL:

const vc = await import("@thi.ng/vclock");

Package sizes (brotli'd, pre-treeshake): ESM: 431 bytes

Dependencies

• @thi.ng/api

Note: @thi.ng/api is in most cases a type-only import (not used at runtime)

API

Generated API docs

TODO

Authors

• Karsten Schmidt

If this project contributes to an academic publication, please cite it as:

@misc{thing-vclock,
  title = "@thi.ng/vclock",
  author = "Karsten Schmidt",
  note = "https://thi.ng/vclock",
  year = 2018
}

License

© 2018 - 2024 Karsten Schmidt // Apache License 2.0