@evolu/common 8.7.0 → 8.9.0

package/src/local-first/Shared.ts

@@ -10,7 +10,11 @@ import {
   isNonEmptyArray,
   type NonEmptyReadonlyArray,
 } from "../Array.ts";
-import { assert } from "../Assert.ts";
+import {
+  assertNonNullable,
+  assertNotSame,
+  assertNotUndefined,
+} from "../Assert.ts";
 import type { Brand } from "../Brand.ts";
 import { createCallbacks } from "../Callbacks.ts";
 import type { ConsoleEntry, ConsoleLevel } from "../Console.ts";
@@ -495,7 +499,7 @@ const createEvoluTenant =
 
     const initDbWorker = (): void => {
       const tabLeaderPort = deps.tabLeaderPortStore.get();
-      assert(tabLeaderPort, "Expected tab leader port.");
+      assertNonNullable(tabLeaderPort);
 
       const dbWorkerChannel = deps.createMessageChannel<
         DbWorkerOutput,
@@ -506,10 +510,7 @@ const createEvoluTenant =
       currentDbWorkerPort.onMessage = (message) => {
         switch (message.type) {
           case "LeaderAcquired": {
-            assert(
-              dbWorkerPort !== currentDbWorkerPort,
-              "Expected a new DbWorker port.",
-            );
+            assertNotSame(dbWorkerPort, currentDbWorkerPort);
             dbWorkerPort?.[Symbol.dispose]();
             dbWorkerPort = currentDbWorkerPort;
             queueRequestInFlight = false;
@@ -775,9 +776,9 @@ const createEvoluTenant =
         } else {
           instance.usedSyncOwners.decrement(syncOwner);
           const claimLeases = instance.claimLeasesBySyncOwner.get(syncOwner);
-          assert(claimLeases, "Expected a ClaimLease for the used owner.");
+          assertNotUndefined(claimLeases);
           const claimLease = claimLeases.pop();
-          assert(claimLease, "Expected a ClaimLease for the used owner.");
+          assertNotUndefined(claimLease);
           claimLease.release();
           if (claimLeases.length === 0) {
             instance.claimLeasesBySyncOwner.delete(syncOwner);

package/src/local-first/Storage.ts

@@ -7,9 +7,9 @@
 import { sha256 } from "@noble/hashes/sha2.js";
 import type { NonEmptyReadonlyArray } from "../Array.ts";
 import { firstInArray, isNonEmptyArray } from "../Array.ts";
-import { assert } from "../Assert.ts";
+import { assert, assertNonNullable } from "../Assert.ts";
 import type { Brand } from "../Brand.ts";
-import { concatBytes } from "../Buffer.ts";
+import { concatBytes } from "../Binary.ts";
 import { decrement } from "../Number.ts";
 import type { RandomDep } from "../Random.ts";
 import { err, ok } from "../Result.ts";
@@ -1602,8 +1602,8 @@ export const readOwnerUsageOrDefault =
     }
 
     const row = firstInArray(result.rows);
-    assert(row.firstTimestamp, "not null");
-    assert(row.lastTimestamp, "not null");
+    assertNonNullable(row.firstTimestamp);
+    assertNonNullable(row.lastTimestamp);
 
     return {
       storedBytes: row.storedBytes,

package/src/local-first/Timestamp.test.ts

@@ -0,0 +1,374 @@
+import { describe, it, test } from "node:test";
+import {
+  assertEqual,
+  assertErr,
+  assertFalse,
+  assertOk,
+  assertTrue,
+} from "../Assert.ts";
+import { increment } from "../Number.ts";
+import { orderNumber } from "../Order.ts";
+import type { Result } from "../Result.ts";
+import { ok } from "../Result.ts";
+import { testCreateDeps } from "../Task.ts";
+import type { Time, TimeDep } from "../Time.ts";
+import { maxMillis, Millis, minMillis, testCreateTime } from "../Time.ts";
+import type {
+  Timestamp,
+  TimestampBytes,
+  TimestampConfigDep,
+  TimestampCounterOverflowError,
+  TimestampDriftError,
+  TimestampTimeOutOfRangeError,
+} from "./Timestamp.ts";
+import {
+  Counter,
+  createInitialTimestamp,
+  createTimestamp,
+  defaultTimestampMaxDrift,
+  maxCounter,
+  minCounter,
+  NodeId,
+  nodeIdBytesToNodeId,
+  nodeIdToNodeIdBytes,
+  orderTimestampBytes,
+  receiveTimestamp,
+  sendTimestamp,
+  timestampBytesToTimestamp,
+  timestampToDateIso,
+  timestampToTimestampBytes,
+} from "./Timestamp.ts";
+
+test("validates Millis", () => {
+  assertFalse(Millis.fromUnknown(-1).ok);
+  assertTrue(Millis.fromUnknown(0).ok);
+  assertTrue(Millis.fromUnknown(maxMillis).ok);
+  assertFalse(Millis.fromUnknown(maxMillis + 1).ok);
+});
+
+test("validates Counter", () => {
+  assertFalse(Counter.fromUnknown(-1).ok);
+  assertTrue(Counter.fromUnknown(0).ok);
+  assertTrue(Counter.fromUnknown(maxCounter).ok);
+  assertFalse(Counter.fromUnknown(maxCounter + 1).ok);
+});
+
+test("validates NodeId", () => {
+  assertFalse(NodeId.fromUnknown("").ok);
+  assertTrue(NodeId.fromUnknown("0000000000000000").ok);
+  assertTrue(NodeId.fromUnknown("aaaaaaaaaaaaaaaa").ok);
+  assertFalse(NodeId.fromUnknown("Aaaaaaaaaaaaaaaa").ok);
+  assertFalse(NodeId.fromUnknown("aaaaaaaaaaaaaaaaa").ok);
+});
+
+describe("NodeId bytes", () => {
+  it("round-trips NodeId", () => {
+    const deps = testCreateDeps();
+    const nodeIds = Array.from(
+      { length: 100 },
+      () => createInitialTimestamp(deps).nodeId,
+    );
+
+    for (const nodeId of nodeIds) {
+      assertEqual(nodeIdBytesToNodeId(nodeIdToNodeIdBytes(nodeId)), nodeId);
+    }
+  });
+});
+
+test("creates the minimum Timestamp by default", () => {
+  assertEqual(createTimestamp(), {
+    counter: 0,
+    millis: 0,
+    nodeId: "0000000000000000",
+  });
+});
+
+test("creates an initial Timestamp", () => {
+  const timestamp = createInitialTimestamp(testCreateDeps());
+
+  assertEqual(timestamp, {
+    counter: 0,
+    millis: 0,
+    nodeId: "9dca8c435bb0779f",
+  });
+});
+
+const makeMillis = (millis: number): Millis => Millis.orThrow(millis);
+
+const deps0: TimeDep & TimestampConfigDep = {
+  time: testCreateTime({ startAt: minMillis }),
+  timestampConfig: { maxDrift: defaultTimestampMaxDrift },
+};
+
+const deps1: TimeDep & TimestampConfigDep = {
+  time: testCreateTime({ startAt: (minMillis + 1) as Millis }),
+  timestampConfig: { maxDrift: defaultTimestampMaxDrift },
+};
+
+describe("sendTimestamp", () => {
+  it("sends monotonically with a monotonic clock", () => {
+    assertOk(sendTimestamp(deps1)(createTimestamp()), {
+      counter: 0,
+      millis: 1,
+      nodeId: "0000000000000000",
+    });
+  });
+
+  it("sends monotonically with a stuttering clock", () => {
+    assertOk(sendTimestamp(deps0)(createTimestamp()), {
+      counter: 1,
+      millis: 0,
+      nodeId: "0000000000000000",
+    });
+  });
+
+  it("sends monotonically with a regressing clock", () => {
+    assertOk(
+      sendTimestamp(deps0)(
+        createTimestamp({ millis: makeMillis(minMillis + 1) }),
+      ),
+      {
+        counter: 1,
+        millis: 1,
+        nodeId: "0000000000000000",
+      },
+    );
+  });
+
+  it("returns TimestampCounterOverflowError for counter overflow", () => {
+    let timestamp: Result<
+      Timestamp,
+      | TimestampDriftError
+      | TimestampCounterOverflowError
+      | TimestampTimeOutOfRangeError
+    > = ok(createTimestamp());
+
+    // Note +1 in 65536.
+    for (let i = 0; i < 65536; i++) {
+      if (timestamp.ok) timestamp = sendTimestamp(deps0)(timestamp.value);
+    }
+
+    assertErr(timestamp, { type: "TimestampCounterOverflowError" });
+  });
+
+  it("returns TimestampDriftError for excessive clock drift", () => {
+    assertErr(
+      sendTimestamp(deps0)(
+        createTimestamp({
+          millis: makeMillis(minMillis + defaultTimestampMaxDrift + 1),
+        }),
+      ),
+      {
+        next: 300001,
+        now: 0,
+        type: "TimestampDriftError",
+      },
+    );
+  });
+
+  it("returns TimestampTimeOutOfRangeError for an invalid clock", () => {
+    const time = testCreateTime();
+    const invalidTime: Time = {
+      ...time,
+      now: (() => -1) as Time["now"],
+    };
+
+    assertErr(
+      sendTimestamp({
+        time: invalidTime,
+        timestampConfig: { maxDrift: defaultTimestampMaxDrift },
+      })(createTimestamp()),
+      { type: "TimestampTimeOutOfRangeError" },
+    );
+  });
+});
+
+describe("receiveTimestamp", () => {
+  const makeNode1Timestamp = (
+    millis = 0,
+    counter = 0,
+    nodeId = "0000000000000001",
+  ): Timestamp =>
+    ({
+      millis: makeMillis(minMillis + millis),
+      counter,
+      nodeId,
+    }) as Timestamp;
+
+  const makeNode2Timestamp = (millis = 0, counter = 0): Timestamp =>
+    makeNode1Timestamp(millis, counter, "0000000000000002");
+
+  it("uses a wall clock later than both timestamps", () => {
+    assertOk(
+      receiveTimestamp(deps1)(makeNode1Timestamp(), makeNode2Timestamp()),
+      {
+        counter: 0,
+        millis: 1,
+        nodeId: "0000000000000001",
+      },
+    );
+  });
+
+  describe("wall clock is behind", () => {
+    it("increments the maximum counter when millis are equal", () => {
+      assertOk(
+        receiveTimestamp(deps1)(
+          makeNode1Timestamp(1, 0),
+          makeNode2Timestamp(1, 1),
+        ),
+        {
+          counter: 2,
+          millis: 1,
+          nodeId: "0000000000000001",
+        },
+      );
+
+      assertOk(
+        receiveTimestamp(deps0)(
+          makeNode1Timestamp(1, 1),
+          makeNode2Timestamp(1, 0),
+        ),
+        {
+          counter: 2,
+          millis: 1,
+          nodeId: "0000000000000001",
+        },
+      );
+    });
+
+    it("increments the counter when local millis is later", () => {
+      assertOk(
+        receiveTimestamp(deps0)(makeNode1Timestamp(2), makeNode2Timestamp(1)),
+        {
+          counter: 1,
+          millis: 2,
+          nodeId: "0000000000000001",
+        },
+      );
+    });
+
+    it("increments the counter when remote millis is later", () => {
+      assertOk(
+        receiveTimestamp(deps0)(makeNode1Timestamp(1), makeNode2Timestamp(2)),
+        {
+          counter: 1,
+          millis: 2,
+          nodeId: "0000000000000001",
+        },
+      );
+    });
+
+    it("returns TimestampDriftError for excessive clock drift", () => {
+      const expected = {
+        next: 300001,
+        now: 0,
+        type: "TimestampDriftError",
+      } as const;
+
+      assertErr(
+        receiveTimestamp(deps0)(
+          createTimestamp({
+            millis: makeMillis(minMillis + defaultTimestampMaxDrift + 1),
+          }),
+          makeNode2Timestamp(),
+        ),
+        expected,
+      );
+
+      assertErr(
+        receiveTimestamp(deps0)(
+          makeNode2Timestamp(),
+          createTimestamp({
+            millis: makeMillis(minMillis + defaultTimestampMaxDrift + 1),
+          }),
+        ),
+        expected,
+      );
+    });
+
+    it("returns TimestampCounterOverflowError for counter overflow", () => {
+      assertErr(
+        receiveTimestamp(deps0)(
+          makeNode1Timestamp(0, maxCounter),
+          makeNode2Timestamp(0, maxCounter),
+        ),
+        { type: "TimestampCounterOverflowError" },
+      );
+    });
+  });
+});
+
+describe("TimestampBytes", () => {
+  it("round-trips and preserves Timestamp order", () => {
+    const decodeFromEncoded = (timestamp: TimestampBytes) =>
+      timestampBytesToTimestamp(timestamp);
+
+    const timestamp = createTimestamp();
+    assertEqual(
+      decodeFromEncoded(timestampToTimestampBytes(timestamp)),
+      timestamp,
+    );
+
+    const lastSafeTimestampEncodedDecoded = decodeFromEncoded(
+      timestampToTimestampBytes(createTimestamp({ millis: maxMillis })),
+    );
+    assertEqual(lastSafeTimestampEncodedDecoded.millis, maxMillis);
+
+    const t1 = timestampToTimestampBytes(
+      createTimestamp({ millis: minMillis }),
+    );
+    const t2 = timestampToTimestampBytes(
+      createTimestamp({
+        millis: Millis.orThrow(increment(minMillis)),
+      }),
+    );
+    assertEqual(orderTimestampBytes(t1, t2), -1);
+    assertEqual(orderTimestampBytes(t2, t1), 1);
+    assertEqual(orderTimestampBytes(t1, t1), 0);
+
+    const t3 = timestampToTimestampBytes(
+      createTimestamp({ counter: minCounter }),
+    );
+    const t4 = timestampToTimestampBytes(
+      createTimestamp({
+        counter: Counter.orThrow(increment(minCounter)),
+      }),
+    );
+    assertEqual(orderTimestampBytes(t3, t4), -1);
+    assertEqual(orderTimestampBytes(t4, t3), 1);
+    assertEqual(orderTimestampBytes(t3, t3), 0);
+
+    const t5 = timestampToTimestampBytes(
+      createTimestamp({ nodeId: "0000000000000000" as NodeId }),
+    );
+    const t6 = timestampToTimestampBytes(
+      createTimestamp({ nodeId: "0000000000000001" as NodeId }),
+    );
+    assertEqual(orderTimestampBytes(t5, t6), -1);
+    assertEqual(orderTimestampBytes(t6, t5), 1);
+    assertEqual(orderTimestampBytes(t5, t5), 0);
+
+    const deps = testCreateDeps();
+    const randomMillis = new Set<Millis>();
+    for (let i = 0; i < 1000; i++) {
+      randomMillis.add(deps.randomLib.int(0, 10000) as Millis);
+    }
+
+    const sortedMillis = [...randomMillis].toSorted(orderNumber);
+    const sortedEncodedMillis = [...randomMillis]
+      .map((millis) => createTimestamp({ millis }))
+      .map(timestampToTimestampBytes)
+      .toSorted(orderTimestampBytes)
+      .map(decodeFromEncoded)
+      .map(({ millis }) => millis);
+
+    assertEqual(sortedEncodedMillis, sortedMillis);
+  });
+});
+
+test("converts Timestamp to DateIso", () => {
+  assertEqual(
+    timestampToDateIso(createTimestamp()),
+    "1970-01-01T00:00:00.000Z",
+  );
+});

package/src/local-first/Timestamp.ts

@@ -4,7 +4,7 @@
  * @module
  */
 
-import { bytesToHex } from "../Buffer.ts";
+import { bytesToHex, hexToBytes } from "../Binary.ts";
 import type { RandomBytesDep } from "../Crypto.ts";
 import { createEqObject, eqNumber, eqString } from "../Eq.ts";
 import { increment } from "../Number.ts";
@@ -99,6 +99,24 @@ export type NodeId = typeof NodeId.Output;
 export const minNodeId = "0000000000000000" as NodeId;
 export const maxNodeId = "ffffffffffffffff" as NodeId;
 
+/** Binary representation of {@link NodeId}. */
+export const NodeIdBytes = /*#__PURE__*/ brand(
+  "NodeIdBytes",
+  /*#__PURE__*/ length(8)(Uint8Array),
+);
+export type NodeIdBytes = typeof NodeIdBytes.Output;
+
+/** Length of {@link NodeIdBytes}. */
+export const nodeIdBytesLength = /*#__PURE__*/ NonNegativeInt.orThrow(8);
+
+/** Converts {@link NodeId} to {@link NodeIdBytes}. */
+export const nodeIdToNodeIdBytes = (nodeId: NodeId): NodeIdBytes =>
+  hexToBytes(nodeId) as NodeIdBytes;
+
+/** Converts {@link NodeIdBytes} to {@link NodeId}. */
+export const nodeIdBytesToNodeId = (nodeIdBytes: NodeIdBytes): NodeId =>
+  bytesToHex(nodeIdBytes) as NodeId;
+
 /**
  * Hybrid Logical Clock timestamp.
  *
@@ -303,11 +321,8 @@ export const timestampToTimestampBytes = (
   value[6] = (counter >> 8) & 0xff;
   value[7] = counter & 0xff;
 
-  // Encode `nodeId` (16-character hex string) into the next 8 bytes.
-  for (let i = 0; i < 8; i++) {
-    const byte = parseInt(nodeId.slice(i * 2, i * 2 + 2), 16);
-    value[8 + i] = byte;
-  }
+  // Encode `nodeId` into the next 8 bytes.
+  value.set(nodeIdToNodeIdBytes(nodeId), 8);
 
   return value as TimestampBytes;
 };
@@ -328,10 +343,7 @@ export const timestampBytesToTimestamp = (
   const counter = (timestamp[6] << 8) | timestamp[7];
 
   // Decode `nodeId` from the last 8 bytes.
-  let nodeId = "";
-  for (let i = 8; i < 16; i++) {
-    nodeId += timestamp[i].toString(16).padStart(2, "0");
-  }
+  const nodeId = nodeIdBytesToNodeId(timestamp.subarray(8) as NodeIdBytes);
 
   return { millis: Number(millis), counter, nodeId } as Timestamp;
 };

package/dist/src/Buffer.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Buffer.d.ts","sourceRoot":"","sources":["../../src/Buffer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3D,OAAO,EACL,UAAU,EACV,WAAW,EACX,WAAW,EACX,UAAU,EACV,WAAW,GACZ,MAAM,yBAAyB,CAAC;AAEjC;;;GAGG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,YAAY,OAAO,EAAE,MAAM,EAK1B;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,MAAM,WAAW,MAAM;IACrB,kDAAkD;IAClD,WAAW,EAAE,MAAM,cAAc,CAAC;IAElC,gEAAgE;IAChE,SAAS,EAAE,MAAM,cAAc,CAAC;IAEhC;;;OAGG;IACH,MAAM,EAAE,CAAC,GAAG,EAAE,UAAU,GAAG,SAAS,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC;IAEtD;;;OAGG;IACH,KAAK,EAAE,MAAM,cAAc,CAAC;IAE5B;;;OAGG;IACH,MAAM,EAAE,CAAC,CAAC,EAAE,cAAc,KAAK,UAAU,CAAC;IAE1C;;;OAGG;IACH,QAAQ,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,CAAC;IAE3C;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,IAAI,CAAC;IAElB;;;;OAIG;IACH,MAAM,EAAE,MAAM,UAAU,CAAC;CAC1B;AAED,8DAA8D;AAC9D,eAAO,MAAM,YAAY,eACX,UAAU,GAAG,SAAS,CAAC,MAAM,CAAC,KACzC,MAgEF,CAAC;AAqDF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,eAAe,WAAY,MAAM,SAAS,SAAS,KAAG,IAelE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,eAAe,WAAY,MAAM,KAAG,SAwBhD,CAAC"}