@evolu/common 6.0.1-preview.3 → 6.0.1-preview.30

package/src/Evolu/Timestamp.ts

@@ -1,18 +1,22 @@
 import { assert } from "../Assert.js";
-import { NanoIdLibDep } from "../NanoId.js";
+import { Brand } from "../Brand.js";
+import { bytesToHex } from "../Buffer.js";
+import { RandomBytesDep } from "../Crypto.js";
+import { createEqObject, eqNumber, eqString } from "../Eq.js";
 import { increment } from "../Number.js";
 import { Order, orderUint8Array } from "../Order.js";
-import { err, getOrThrow, ok, Result } from "../Result.js";
+import { err, ok, Result } from "../Result.js";
 import { TimeDep } from "../Time.js";
 import {
   brand,
+  InferType,
   lessThanOrEqualTo,
   NonNegativeInt,
   object,
   regex,
   String,
+  Uint8Array,
 } from "../Type.js";
-import { Brand } from "../Types.js";
 
 export interface TimestampConfig {
   /**
@@ -30,7 +34,6 @@ export interface TimestampConfigDep {
 export type TimestampError =
   | TimestampDriftError
   | TimestampCounterOverflowError
-  | TimestampDuplicateNodeError
   | TimestampTimeOutOfRangeError;
 
 export interface TimestampDriftError {
@@ -43,11 +46,6 @@ export interface TimestampCounterOverflowError {
   readonly type: "TimestampCounterOverflowError";
 }
 
-export interface TimestampDuplicateNodeError {
-  readonly type: "TimestampDuplicateNodeError";
-  readonly nodeId: NodeId;
-}
-
 export interface TimestampTimeOutOfRangeError {
   readonly type: "TimestampTimeOutOfRangeError";
 }
@@ -95,14 +93,17 @@ export const maxCounter = 65535 as Counter;
  *
  * https://lemire.me/blog/2019/12/12/are-64-bit-random-identifiers-free-from-collision
  *
- * What will happen if a different device generates the same NodeId?
+ * What happens if different devices generate the same NodeId?
  *
- * If the device belongs to a different owner, nothing will happen because
- * different owner have different owner IDs. Timestamps are partitioned by
- * OwnerId.
+ * If devices with the same NodeId use different owners, no issues occur.
  *
- * If the device belongs to the same owner, the other device will return
- * {@link TimestampDuplicateNodeError}.
+ * If devices with the same NodeId use the same owner, problems only arise when
+ * they generate CRDT messages with identical timestamps (same millis, counter,
+ * and NodeId). In this case, the protocol sync algorithm treats them as the
+ * same message: the first will be synced with the relay, while the affected
+ * message will not be delivered. The affected devices will see different data
+ * yet they will think they are synced. This is extremely rare and can be
+ * resolved by resetting one device to generate a new NodeId.
  */
 export const NodeId = regex("NodeId", /^[a-f0-9]{16}$/)(String);
 export type NodeId = typeof NodeId.Type;
@@ -113,16 +114,73 @@ export const maxNodeId = "ffffffffffffffff" as NodeId;
 /**
  * Hybrid Logical Clock timestamp.
  *
+ * Timestamps serve as globally unique, causally ordered identifiers for CRDT
+ * messages in Evolu's sync protocol.
+ *
+ * ### Why Hybrid Logical Clocks
+ *
+ * Evolu uses Hybrid Logical Clocks (HLC), which combine physical time (millis)
+ * with a logical counter. This hybrid approach preserves causality like logical
+ * clocks while staying close to physical time for better human
+ * interpretability.
+ *
+ * The counter component ensures causality is maintained even when physical
+ * clocks are imperfect. When clocks drift or operations occur concurrently, the
+ * counter increments to establish a total order. This means Evolu achieves
+ * well-defined, eventually-consistent behavior regardless of physical clock
+ * accuracy.
+ *
+ * Vector clocks can accurately track causality and detect concurrent
+ * operations, but they require unbounded space in peer-to-peer systems and
+ * crucially, still don't solve our fundamental problem: when they detect
+ * operations as concurrent, we still need a deterministic way to choose a
+ * winner. Additionally, any deterministic conflict resolution can be gamed by
+ * malicious actors.
+ *
+ * HLC timestamps work well in practice because modern device clocks accurately
+ * reflect the order of sequential edits in the common case. Evolu's `maxDrift`
+ * configuration protects against buggy clocks and prevents problematic
+ * future-dated entries from propagating through the network.
+ *
+ * ### References
+ *
  * - https://muratbuffalo.blogspot.com/2014/07/hybrid-logical-clocks.html
  * - https://sergeiturukin.com/2017/06/26/hybrid-logical-clocks.html
  * - https://jaredforsyth.com/posts/hybrid-logical-clocks/
+ * - https://willowprotocol.org/more/timestamps_really/index.html
+ *
+ * ### Privacy Considerations
+ *
+ * Timestamps are metadata visible to relays and collaborators. While it can be
+ * considered a privacy leak, let us explain why it's necessary, and how to
+ * avoid it if maximum privacy is required.
+ *
+ * With real-time communication, participants always see activity (receiving
+ * bytes). We cannot trust anyone not to store that information, so explicitly
+ * exposing timestamps doesn't add additional risk.
+ *
+ * If we really want not to leak user activity, we can implement a local write
+ * queue:
+ *
+ * 1. Write changes immediately to a local-only table
+ * 2. Periodically/randomly flush messages to sync tables
+ * 3. This decouples user activity from sync timing
+ *
+ * Tradeoff: It breaks real-time collaboration.
  */
 export const Timestamp = object({
   millis: Millis,
   counter: Counter,
   nodeId: NodeId,
 });
-export type Timestamp = typeof Timestamp.Type;
+export interface Timestamp extends InferType<typeof Timestamp> {}
+
+/** Equality function for comparing {@link Timestamp}. */
+export const eqTimestamp = createEqObject<Timestamp>({
+  millis: eqNumber,
+  counter: eqNumber,
+  nodeId: eqString,
+});
 
 export const createTimestamp = ({
   millis = minMillis,
@@ -130,14 +188,12 @@ export const createTimestamp = ({
   nodeId = minNodeId,
 }: Partial<Timestamp> = {}): Timestamp => ({ millis, counter, nodeId });
 
-const hexAlphabet = "0123456789abcdef";
-
-export const createInitialTimestamp = (deps: NanoIdLibDep): Timestamp => {
-  const nodeId = deps.nanoIdLib.customAlphabet(hexAlphabet, 16)() as NodeId;
+export const createInitialTimestamp = (deps: RandomBytesDep): Timestamp => {
+  const nodeId = bytesToHex(deps.randomBytes.create(8)) as NodeId;
   return createTimestamp({ nodeId });
 };
 
-/** TimestampString is a sortable string version of {@link Timestamp}. */
+/** Sortable string representation of {@link Timestamp}. */
 export type TimestampString = string & Brand<"TimestampString">;
 
 export const timestampToTimestampString = (t: Timestamp): TimestampString =>
@@ -222,12 +278,8 @@ export const receiveTimestamp =
     Timestamp,
     | TimestampDriftError
     | TimestampCounterOverflowError
-    | TimestampDuplicateNodeError
     | TimestampTimeOutOfRangeError
   > => {
-    if (local.nodeId === remote.nodeId) {
-      return err({ type: "TimestampDuplicateNodeError", nodeId: local.nodeId });
-    }
     const millis = getNextMillis(deps)([local.millis, remote.millis]);
     if (!millis.ok) return millis;
 
@@ -249,18 +301,19 @@ export const receiveTimestamp =
     });
   };
 
-/** BinaryTimestamp is a binary and sortable version of {@link Timestamp} for DB. */
-export type BinaryTimestamp = Uint8Array & Brand<"BinaryTimestamp">;
+/** Sortable bytes representation of {@link Timestamp}. */
+export const TimestampBytes = brand("TimestampBytes", Uint8Array);
+export type TimestampBytes = typeof TimestampBytes.Type;
 
-export const binaryTimestampLength = getOrThrow(NonNegativeInt.from(16));
+export const timestampBytesLength = NonNegativeInt.orThrow(16);
 
-export const timestampToBinaryTimestamp = (
+export const timestampToTimestampBytes = (
   timestamp: Timestamp,
-): BinaryTimestamp => {
+): TimestampBytes => {
   const { millis, counter, nodeId } = timestamp;
 
   // 6 bytes for millis, 2 bytes for counter, 8 bytes for nodeId.
-  const value = new Uint8Array(16);
+  const value = new globalThis.Uint8Array(16);
 
   // Encode `millis` into the first 6 bytes.
   const millisBigInt = BigInt(millis);
@@ -281,11 +334,11 @@ export const timestampToBinaryTimestamp = (
     value[8 + i] = byte;
   }
 
-  return value as BinaryTimestamp;
+  return value as TimestampBytes;
 };
 
-export const binaryTimestampToTimestamp = (
-  timestamp: BinaryTimestamp,
+export const timestampBytesToTimestamp = (
+  timestamp: TimestampBytes,
 ): Timestamp => {
   // Decode `millis` from the first 6 bytes.
   const millis =
@@ -308,4 +361,4 @@ export const binaryTimestampToTimestamp = (
   return { millis: Number(millis), counter, nodeId } as Timestamp;
 };
 
-export const orderBinaryTimestamp: Order<BinaryTimestamp> = orderUint8Array;
+export const orderTimestampBytes: Order<TimestampBytes> = orderUint8Array;

package/src/Identicon.ts

@@ -0,0 +1,197 @@
+import type { Brand } from "./Brand.js";
+import { Id, idToIdBytes } from "./Type.js";
+import { md5 } from "@noble/hashes/legacy.js";
+
+/**
+ * SVG string representing a visual identicon for an {@link Id}, created with
+ * {@link createIdenticon}.
+ */
+export type Identicon = string & Brand<"Identicon">;
+
+/** {@link Identicon} style. */
+export type IdenticonStyle = "github" | "quadrant" | "gradient" | "sutnar";
+
+/**
+ * Creates a deterministic identicon SVG from an {@link Id}.
+ *
+ * Works with any {@link Id} including branded IDs like `OwnerId`, etc.
+ *
+ * Available styles:
+ *
+ * - `"github"` (default): 5x5 grid with horizontal mirroring (GitHub-style)
+ * - `"quadrant"`: 2x2 grid with direct RGB color mapping from bytes
+ * - `"gradient"`: Diagonal stripes with smooth color gradients
+ * - `"sutnar"`: Three compositional variants with adaptive colors
+ *
+ * ### Example
+ *
+ * ```ts
+ * const svg = createIdenticon(id);
+ * const quadrantStyle = createIdenticon(id, "quadrant");
+ * const gradientStyle = createIdenticon(id, "gradient");
+ * const sutnarStyle = createIdenticon(id, "sutnar");
+ *
+ * // Works with branded IDs
+ * const ownerSvg = createIdenticon(ownerId);
+ * ```
+ */
+export const createIdenticon = (
+  id: Id,
+  style: IdenticonStyle = "github",
+): Identicon => {
+  const bytes = idToIdBytes(id);
+
+  switch (style) {
+    case "github": {
+      // GitHub-style identicon: MD5 hash the bytes first
+      const hashedBytes = md5(bytes);
+
+      // Map function for value ranges
+      const map = (
+        value: number,
+        inMin: number,
+        inMax: number,
+        outMin: number,
+        outMax: number,
+      ): number =>
+        ((value - inMin) * (outMax - outMin)) / (inMax - inMin) + outMin;
+
+      // Extract 12-bit hue from bytes[12] (lower 4 bits) + bytes[13]
+      const h = ((hashedBytes[12] & 0x0f) << 8) | hashedBytes[13];
+      const hue = map(h, 0, 4095, 0, 360);
+      const saturation = 65 - map(hashedBytes[14], 0, 255, 0, 20);
+      const lightness = 75 - map(hashedBytes[15], 0, 255, 0, 20);
+
+      const fgColor = `hsl(${hue},${saturation}%,${lightness}%)`;
+      const bgColor = `hsl(${hue},${saturation}%,90%)`;
+
+      let rects = `<rect width="5" height="5" fill="${bgColor}"/>`;
+
+      // Extract nibbles and generate pattern
+      let nibbleIndex = 0;
+      for (let x = 2; x >= 0; x--) {
+        for (let y = 0; y < 5; y++) {
+          const byte = hashedBytes[Math.floor(nibbleIndex / 2)];
+          const nibble = nibbleIndex % 2 === 0 ? byte >> 4 : byte & 0x0f;
+          const paint = nibble % 2 === 0;
+          nibbleIndex++;
+
+          if (paint) {
+            rects += `<rect x="${x}" y="${y}" width="1" height="1" fill="${fgColor}"/>`;
+            const mx = 4 - x;
+            if (mx !== x) {
+              rects += `<rect x="${mx}" y="${y}" width="1" height="1" fill="${fgColor}"/>`;
+            }
+          }
+        }
+      }
+
+      return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 5 5" shape-rendering="crispEdges">${rects}</svg>` as Identicon;
+    }
+
+    case "quadrant": {
+      const toHex = (b: number): string => b.toString(16).padStart(2, "0");
+      let rects = "";
+      for (let i = 0; i < 4; i++) {
+        const x = i % 2;
+        const y = Math.floor(i / 2);
+        const r = bytes[i * 3];
+        const g = bytes[i * 3 + 1];
+        const b = bytes[i * 3 + 2];
+        const color = `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+        rects += `<rect x="${x}" y="${y}" width="1" height="1" fill="${color}"/>`;
+      }
+      return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 2 2">${rects}</svg>` as Identicon;
+    }
+
+    case "gradient": {
+      // Smooth color gradients with diagonal stripes.
+      const toHex = (b: number): string => b.toString(16).padStart(2, "0");
+
+      // Generate colors from bytes.
+      const color1 = `#${toHex(bytes[0])}${toHex(bytes[1])}${toHex(bytes[2])}`;
+      const color2 = `#${toHex(bytes[3])}${toHex(bytes[4])}${toHex(bytes[5])}`;
+      const color3 = `#${toHex(bytes[6])}${toHex(bytes[7])}${toHex(bytes[8])}`;
+
+      let defs = "";
+      let shapes = "";
+
+      // Diagonal stripes with gradient.
+      defs += `<linearGradient id="grad1-${id}" x1="0%" y1="0%" x2="0%" y2="100%">`;
+      defs += `<stop offset="0%" style="stop-color:${color1};stop-opacity:1" />`;
+      defs += `<stop offset="100%" style="stop-color:${color2};stop-opacity:1" />`;
+      defs += `</linearGradient>`;
+
+      defs += `<linearGradient id="grad2-${id}" x1="0%" y1="0%" x2="0%" y2="100%">`;
+      defs += `<stop offset="0%" style="stop-color:${color2};stop-opacity:1" />`;
+      defs += `<stop offset="100%" style="stop-color:${color3};stop-opacity:1" />`;
+      defs += `</linearGradient>`;
+
+      shapes += `<rect width="100" height="100" fill="url(#grad1-${id})"/>`;
+
+      const stripeWidth = 15 + (bytes[9] / 255) * 20;
+      const angle = 30 + (bytes[10] / 255) * 60;
+
+      shapes += `<rect x="20" y="-50" width="${stripeWidth}" height="200" fill="url(#grad2-${id})" transform="rotate(${angle} 50 50)" opacity="0.7"/>`;
+      shapes += `<rect x="60" y="-50" width="${stripeWidth}" height="200" fill="url(#grad2-${id})" transform="rotate(${angle} 50 50)" opacity="0.5"/>`;
+
+      return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><defs>${defs}</defs>${shapes}</svg>` as Identicon;
+    }
+
+    case "sutnar": {
+      // Three compositional variants with adaptive colors.
+      const hue = (bytes[0] / 255) * 360;
+      const saturation = 50 + (bytes[1] / 255) * 30;
+      const lightness = 50 + (bytes[2] / 255) * 20;
+
+      // Generate palette from base hue with variations
+      const toHsl = (h: number, s: number, l: number) =>
+        `hsl(${h},${s}%,${l}%)`;
+
+      const color1 = toHsl(hue, saturation, lightness);
+      const color2 = toHsl((hue + 120) % 360, saturation, lightness);
+      const color3 = toHsl((hue + 240) % 360, saturation, lightness);
+      const color4 = toHsl(hue, saturation * 0.3, lightness * 0.5);
+      const color5 = toHsl(
+        hue,
+        saturation * 0.5,
+        Math.min(lightness * 1.3, 90),
+      );
+
+      const palette = [color1, color2, color3, color4, color5] as const;
+
+      // Layout variant based on first byte.
+      const variant = bytes[3] % 3;
+
+      let shapes = "";
+
+      // Almost white background with subtle tint.
+      shapes += `<rect width="100" height="100" fill="${toHsl(hue, 10, 95)}"/>`;
+
+      if (variant === 0) {
+        // Composition A: Circle + horizontal bar.
+        const circleColor = palette[bytes[4] % palette.length];
+        const barColor = palette[(bytes[4] + 1) % palette.length];
+
+        shapes += `<circle cx="30" cy="50" r="22" fill="${circleColor}"/>`;
+        shapes += `<rect x="60" y="40" width="35" height="20" fill="${barColor}"/>`;
+      } else if (variant === 1) {
+        // Composition B: Vertical bar + circle.
+        const barColor = palette[bytes[5] % palette.length];
+        const circleColor = palette[(bytes[5] + 1) % palette.length];
+
+        shapes += `<rect x="15" y="10" width="18" height="80" fill="${barColor}"/>`;
+        shapes += `<circle cx="70" cy="50" r="15" fill="${circleColor}"/>`;
+      } else {
+        // Composition C: Square + circle.
+        const squareColor = palette[bytes[6] % palette.length];
+        const circleColor = palette[(bytes[6] + 1) % palette.length];
+
+        shapes += `<rect x="20" y="20" width="30" height="30" fill="${squareColor}"/>`;
+        shapes += `<circle cx="70" cy="70" r="18" fill="${circleColor}"/>`;
+      }
+
+      return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">${shapes}</svg>` as Identicon;
+    }
+  }
+};

package/src/Instances.ts

@@ -0,0 +1,90 @@
+/**
+ * Manages disposable instances by key, ensuring exactly one instance per key.
+ *
+ * Use cases:
+ *
+ * - One mutex per key to prevent concurrent writes
+ * - Preserving state during hot module reloading
+ *
+ * **Important:** Do not use this as global shared state. Use it locally or pass
+ * it as a dependency instead. The only exception is for hot reloading support,
+ * where Evolu uses it to ensure only one instance exists across module reloads
+ * (having two Evolu instances with the same name would mean two SQLite
+ * connections to the same file, which could corrupt data).
+ */
+export interface Instances<K extends string, T extends Disposable>
+  extends Disposable {
+  /**
+   * Ensures an instance exists for the given key, creating it if necessary. If
+   * the instance already exists, the optional `onCacheHit` callback is invoked
+   * to update the existing instance.
+   */
+  readonly ensure: (
+    key: K,
+    create: () => T,
+    onCacheHit?: (instance: T) => void,
+  ) => T;
+
+  /** Gets an instance by key, or returns `null` if it doesn't exist. */
+  readonly get: (key: K) => T | null;
+
+  /** Checks if an instance exists for the given key. */
+  readonly has: (key: K) => boolean;
+
+  /**
+   * Deletes and disposes an instance by key. Returns `true` if the instance
+   * existed and was deleted, `false` otherwise.
+   */
+  readonly delete: (key: K) => boolean;
+}
+
+/** Creates an {@link Instances}. */
+export const createInstances = <
+  K extends string,
+  T extends Disposable,
+>(): Instances<K, T> => {
+  const instances = new Map<K, T>();
+
+  return {
+    ensure: (key, create, onCacheHit) => {
+      let instance = instances.get(key);
+
+      if (instance == null) {
+        instance = create();
+        instances.set(key, instance);
+      } else if (onCacheHit) {
+        onCacheHit(instance);
+      }
+
+      return instance;
+    },
+
+    get: (key) => instances.get(key) ?? null,
+
+    has: (key) => instances.has(key),
+
+    delete: (key) => {
+      const instance = instances.get(key);
+      if (instance == null) return false;
+      instances.delete(key);
+      instance[Symbol.dispose]();
+      return true;
+    },
+
+    [Symbol.dispose]: () => {
+      const errors: Array<unknown> = [];
+      for (const instance of instances.values()) {
+        try {
+          instance[Symbol.dispose]();
+        } catch (error) {
+          errors.push(error);
+        }
+      }
+      instances.clear();
+      if (errors.length === 1) throw errors[0];
+      if (errors.length > 1) {
+        throw new AggregateError(errors, "Multiple disposal errors occurred");
+      }
+    },
+  };
+};