Initial implementation

Author: etienne-dldc

.github/workflows/publish.yml

@@ -0,0 +1,22 @@
+name: Publish
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: denoland/setup-deno@v1
+        with:
+          deno-version: v2.x
+
+      - run: deno task check
+
+      - run: npx jsr publish

.gitignore

@@ -0,0 +1,18 @@
+.DS_Store
+
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+*.tsbuildinfo
+coverage
+node_modules/
+jspm_packages/
+.env
+.env.test
+
+dist

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+  "deno.enable": true,
+  "editor.defaultFormatter": "denoland.vscode-deno",
+  "npm.autoDetect": "off"
+}

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Etienne Dldc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,138 @@
+# Hybrid Logical Clock
+
+A robust, minimal, and standards-compliant Hybrid Logical Clock (HLC)
+implementation for Deno and JavaScript/TypeScript. HLCs are used in distributed
+systems to generate timestamps that combine physical and logical time, enabling
+causality tracking and event ordering even in the presence of clock skew.
+
+## Installation
+
+```sh
+deno add jsr:@dldc/hybrid-logical-clock
+```
+
+## Overview
+
+This package provides a simple and safe way to generate and merge Hybrid Logical
+Clock timestamps. It is ideal for distributed systems, CRDTs, event sourcing,
+and any scenario where you need to track causality and order events across
+nodes.
+
+- **Monotonic and Causally Consistent**: Ensures timestamps never go backward
+  and reflect causal relationships.
+- **Customizable**: Supports custom node IDs, wall clock sources, and drift
+  limits.
+- **Safe**: Detects and throws on excessive clock drift or logical counter
+  overflow.
+
+## Usage Example
+
+```ts
+import {
+  compareHLCTimestamps,
+  createHLC,
+  parseHLCTimestamp,
+} from "@dldc/hybrid-logical-clock";
+
+// Create a new HLC instance (nodeId is optional)
+const hlc = createHLC({ nodeId: "node-1" });
+
+// Generate a timestamp for a local/send event
+const t1 = hlc.send();
+
+// Merge a remote timestamp (e.g., from another node)
+const remote = parseHLCTimestamp("2025-05-22T12:34:56.789Z|00000001|node-2");
+const t2 = hlc.receive(remote!);
+
+// Serialize/deserialize
+const str = t2.toString();
+const parsed = parseHLCTimestamp(str);
+
+// Compare timestamps
+const cmp = compareHLCTimestamps(t1, t2); // -1, 0, or 1
+```
+
+## Library Specificities
+
+- **Drift Detection**: If the physical time difference between local and remote
+  exceeds `maxDrift` (default: 5 minutes), an error is thrown.
+- **Logical Counter Overflow**: If the logical counter exceeds 99,999,999, an
+  error is thrown.
+- **Timestamps**: Timestamps are objects with `{ ts, cl, id, toString() }` and
+  serialize to ISO8601|logical|nodeId.
+- **Customizable**: You can provide your own node ID, wall clock function, and
+  drift limit.
+
+## API Reference
+
+### `createHLC(options?: HLCInstanceOptions): HLCInstance`
+
+Creates a new Hybrid Logical Clock instance.
+
+**Options:**
+
+- `nodeId?: string` — Unique identifier for this node (default: random UUID).
+- `getWallClockTime?: () => number` — Function to get current time (default:
+  `Date.now()`).
+- `maxDrift?: number` — Maximum allowed drift in ms (default: 5 minutes).
+
+**Returns:** `HLCInstance` object:
+
+- `nodeId: string` — The node's unique ID.
+- `send(): HLCTimestamp` — Generate a new timestamp for a local/send event.
+- `receive(remote: HLCTimestamp): HLCTimestamp` — Merge a remote timestamp.
+- `MIN_TIMESTAMP: HLCTimestamp` — Minimum possible timestamp for this node.
+- `MAX_TIMESTAMP: HLCTimestamp` — Maximum possible timestamp for this node.
+
+---
+
+### `HLCTimestamp`
+
+Represents a timestamp:
+
+- `ts: number` — Physical time (ms since epoch).
+- `cl: number` — Logical counter.
+- `id: string` — Node ID.
+- `toString(): string` — String representation
+  (`YYYY-MM-DDTHH:mm:ss.sssZ|00000001|nodeId`).
+
+---
+
+### `compareHLCTimestamps(t1: HLCTimestamp, t2: HLCTimestamp): number`
+
+Compares two timestamps.
+
+- Returns `-1` if `t1 < t2`, `0` if equal, `1` if `t1 > t2`.
+
+---
+
+### `serializeHLC(hlc: HLCTimestamp): string`
+
+Serializes a timestamp to string.
+
+---
+
+### `parseHLCTimestamp(str: string): HLCTimestamp | null`
+
+Parses a string into a timestamp, or returns `null` if invalid.
+
+---
+
+## Example: Handling Events
+
+```ts
+const hlcA = createHLC({ nodeId: "A" });
+const hlcB = createHLC({ nodeId: "B" });
+
+// Node A sends an event
+const tsA = hlcA.send();
+
+// Node B receives the event from A
+const tsB = hlcB.receive(tsA);
+
+// Now, tsB > tsA and reflects the causal relationship
+```
+
+## License
+
+MIT

deno.json

@@ -0,0 +1,24 @@
+{
+  "name": "@dldc/hybrid-logical-clock",
+  "version": "0.0.0",
+  "exports": "./mod.ts",
+  "imports": {
+    "@std/expect": "jsr:@std/expect@^1.0.15"
+  },
+  "tasks": {
+    "test:run": "deno test -A",
+    "test:watch": "deno test --watch",
+    "bump": "deno run -A jsr:@mys/bump@1",
+    "deps:outdated": "deno outdated",
+    "deps:update": "deno outdated --update --latest --interactive",
+    "check": "deno fmt --check . && deno lint . && deno check **/*.ts && deno task test:run",
+    "test:coverage": "deno test -A --coverage=coverage && deno coverage coverage --html"
+  },
+  "lint": {
+    "rules": {
+      "exclude": [
+        "no-explicit-any"
+      ]
+    }
+  }
+}

deno.lock

@@ -0,0 +1,3 @@
+export * from "./src/defaults.ts";
+export * from "./src/hlc.ts";
+export * from "./src/types.ts";

mod.ts

@@ -0,0 +1,36 @@
+/**
+ * The default maximum allowed drift (in milliseconds) between local and remote physical clocks.
+ * Used to detect and prevent excessive clock skew. Default: 5 minutes.
+ */
+export const DEFAULT_MAX_DRIFT = 5 * 60 * 1000; // 5 minutes
+
+/**
+ * The default function to get the current wall clock time (in ms since epoch).
+ * By default, uses Date.now().
+ */
+export const DEFAULT_WALL_CLOCK_TIME = () => Date.now();
+
+/**
+ * The default function to generate a unique node identifier for a clock instance.
+ * By default, uses crypto.randomUUID().
+ */
+export const DEFAULT_CREATE_NODE_ID = () => crypto.randomUUID();
+
+/**
+ * The number of digits used for the logical clock counter in string representations.
+ * Default: 8 digits (e.g., 00000001).
+ */
+export const LOGICAL_CLOCK_LENGTH = 8; // 8 digits
+
+/**
+ * The maximum value for the logical clock counter.
+ * Default: 99999999 (8 digits).
+ */
+export const MAX_LOGICAL_CLOCK = Math.pow(10, LOGICAL_CLOCK_LENGTH) - 1; // 99999999
+
+/**
+ * The maximum allowed epoch timestamp (in ms since epoch).
+ * After year 9999, ISO format adds a + sign to the year which makes it not sortable.
+ * Default: 9999-12-31T23:59:59.999Z
+ */
+export const MAX_EPOCH = 253402300799999; // 9999-12-31T23:59:59.999Z