@evolu/common 6.0.1-preview.2 → 6.0.1-preview.21

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;
@@ -122,7 +123,14 @@ export const Timestamp = object({
   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 +138,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 +228,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 +251,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 +284,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 +311,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/ManyToManyMap.ts

@@ -1,22 +1,84 @@
-/** Represents a many-to-many mapping between keys and values. */
+import { assert } from "./Assert.js";
+
+/**
+ * Bidirectional many-to-many map between keys and values.
+ *
+ * Why useful:
+ *
+ * - Provides O(1) (amortized) forward lookup (key -> values) and reverse lookup
+ *   (value -> keys) without maintaining two maps manually and risking them
+ *   diverging.
+ * - Natural fit for pub/sub style relations such as ownerId ↔ WebSocket, tag ↔
+ *   item, user ↔ role, entity ↔ subscription where both directions are
+ *   frequently queried.
+ * - Supports fast membership tests via `hasPair`, `hasKey`, and `hasValue`.
+ * - Iteration helpers (`forEach`, iterator) allow treating the structure as an
+ *   edge list when needed.
+ *
+ * Complexity:
+ *
+ * - `add` / `remove` / `has*` / `get*` each perform a constant number of Map/Set
+ *   operations (O(1) expected).
+ * - `deleteKey` and `deleteValue` are O(d) where d is the number of associated
+ *   values / keys (the degree). This is optimal because every associated pair
+ *   must be touched once.
+ * - In the Relay use case a socket (value) typically has only dozens of owners
+ *   (degree small), and connection closes (triggering deleteValue) are
+ *   relatively infrequent, so O(d) is acceptable.
+ *
+ * Object identity:
+ *
+ * - Keys and values are compared by reference (standard Map / Set semantics).
+ *   Structural hashing of objects in JavaScript is non-trivial, can be
+ *   expensive, and collision-prone if done naively. Prefer using stable
+ *   primitive identifiers (ids, strings) instead of attempting to hash full
+ *   object structures.
+ * - If structural equivalence is truly required, wrap objects in an adapter that
+ *   supplies a canonical hash/id and stores/retrieves the original objects
+ *   separately. This is a rare need; avoid unless you have clear requirements.
+ */
 export interface ManyToManyMap<K, V> {
-  /** Adds a key-value association to the map. */
-  add: (key: K, value: V) => ManyToManyMap<K, V>;
-
-  /** Removes a specific key-value association. */
+  /**
+   * Adds a key-value association to the map. Returns true if the pair was newly
+   * added, false if it already existed.
+   */
+  add: (key: K, value: V) => boolean;
+
+  /**
+   * Removes a specific key-value association. Returns true if the pair existed
+   * and was removed, false if it was not present.
+   */
   remove: (key: K, value: V) => boolean;
 
-  /** Gets all values associated with a key. */
-  getValues: (key: K) => Set<V> | undefined;
-
-  /** Gets all keys associated with a value. */
-  getKeys: (value: V) => Set<K> | undefined;
+  /**
+   * Gets all values associated with a key. Returned set is the internal Set
+   * instance typed as ReadonlySet. Do not mutate.
+   */
+  getValues: (key: K) => ReadonlySet<V> | undefined;
+
+  /**
+   * Gets all keys associated with a value. Returned set is the internal Set
+   * instance typed as ReadonlySet. Do not mutate.
+   */
+  getKeys: (value: V) => ReadonlySet<K> | undefined;
+
+  /**
+   * Iterates over each key-value pair (in insertion order of keys, then values
+   * per key).
+   */
+  forEach: (callback: (key: K, value: V) => void) => void;
+
+  /**
+   * Iterator over all key-value pairs enabling for..of and spread. Yields
+   * readonly [key, value] tuples.
+   */
+  readonly [Symbol.iterator]: () => IterableIterator<readonly [K, V]>;
 
   /** Checks if a specific key-value pair exists. */
   hasPair: (key: K, value: V) => boolean;
 
   /** Checks if a key exists in the map. */
-  hasKey(key: K): boolean;
+  hasKey: (key: K) => boolean;
 
   /** Checks if a value exists in the map. */
   hasValue: (value: V) => boolean;
@@ -28,17 +90,26 @@ export interface ManyToManyMap<K, V> {
   deleteValue: (value: V) => boolean;
 
   /** Clears all associations in the map. */
-  clear(): void;
+  clear: () => void;
+
+  /** Number of distinct keys currently present. */
+  keyCount: () => number;
+  /** Number of distinct values currently present. */
+  valueCount: () => number;
+  /** Number of key-value pairs (associations) currently stored. */
+  pairCount: () => number;
 }
 
 /** Creates a {@link ManyToManyMap}. */
 export const createManyToManyMap = <K, V>(): ManyToManyMap<K, V> => {
   const forwardMap = new Map<K, Set<V>>();
   const reverseMap = new Map<V, Set<K>>();
+  let pairCountInternal = 0;
 
   const map: ManyToManyMap<K, V> = {
     add(key: K, value: V) {
       let values = forwardMap.get(key);
+      if (values?.has(value)) return false;
       if (!values) {
         values = new Set<V>();
         forwardMap.set(key, values);
@@ -51,8 +122,8 @@ export const createManyToManyMap = <K, V>(): ManyToManyMap<K, V> => {
         reverseMap.set(value, keys);
       }
       keys.add(key);
-
-      return map;
+      pairCountInternal++;
+      return true;
     },
 
     remove(key: K, value: V) {
@@ -65,24 +136,41 @@ export const createManyToManyMap = <K, V>(): ManyToManyMap<K, V> => {
       }
 
       const keys = reverseMap.get(value);
-      if (keys?.size) {
-        keys.delete(key);
-        if (keys.size === 0) {
-          reverseMap.delete(value);
-        }
-      }
+      assert(keys, "Key-value mapping inconsistency");
 
+      keys.delete(key);
+      if (keys.size === 0) {
+        reverseMap.delete(value);
+      }
+      pairCountInternal--;
       return true;
     },
 
-    getValues(key: K) {
+    getValues(key: K): ReadonlySet<V> | undefined {
       return forwardMap.get(key);
     },
 
-    getKeys(value: V) {
+    getKeys(value: V): ReadonlySet<K> | undefined {
       return reverseMap.get(value);
     },
 
+    forEach(callback: (key: K, value: V) => void) {
+      for (const [key, values] of forwardMap) {
+        for (const value of values) callback(key, value);
+      }
+    },
+
+    [Symbol.iterator](): IterableIterator<readonly [K, V]> {
+      const iterator = function* () {
+        for (const [key, values] of forwardMap) {
+          for (const value of values) {
+            yield [key, value] as const;
+          }
+        }
+      };
+      return iterator();
+    },
+
     hasPair(key: K, value: V) {
       const values = forwardMap.get(key);
       return values?.has(value) ?? false;
@@ -99,7 +187,7 @@ export const createManyToManyMap = <K, V>(): ManyToManyMap<K, V> => {
     deleteKey(key: K) {
       const values = forwardMap.get(key);
       if (!values) return false;
-
+      const removed = values.size;
       for (const value of values) {
         const keys = reverseMap.get(value);
         if (keys) {
@@ -110,13 +198,14 @@ export const createManyToManyMap = <K, V>(): ManyToManyMap<K, V> => {
         }
       }
       forwardMap.delete(key);
+      pairCountInternal -= removed;
       return true;
     },
 
     deleteValue(value: V) {
       const keys = reverseMap.get(value);
       if (!keys) return false;
-
+      const removed = keys.size;
       for (const key of keys) {
         const values = forwardMap.get(key);
         if (values) {
@@ -127,12 +216,26 @@ export const createManyToManyMap = <K, V>(): ManyToManyMap<K, V> => {
         }
       }
       reverseMap.delete(value);
+      pairCountInternal -= removed;
       return true;
     },
 
     clear() {
       forwardMap.clear();
       reverseMap.clear();
+      pairCountInternal = 0;
+    },
+
+    keyCount() {
+      return forwardMap.size;
+    },
+
+    valueCount() {
+      return reverseMap.size;
+    },
+
+    pairCount() {
+      return pairCountInternal;
     },
   };
 

package/src/Number.ts

@@ -2,12 +2,8 @@ import { NonEmptyReadonlyArray } from "./Array.js";
 import { assertNonEmptyReadonlyArray } from "./Assert.js";
 import { err, ok, Result } from "./Result.js";
 import { NonNegativeInt, PositiveInt } from "./Type.js";
-import {
-  IntentionalNever,
-  IsBranded,
-  Predicate,
-  WidenLiteral,
-} from "./Types.js";
+import { IntentionalNever, Predicate, WidenLiteral } from "./Types.js";
+import { IsBranded } from "./Brand.js";
 
 export const increment = (n: number): number => n + 1;
 

package/src/Random.ts

@@ -7,8 +7,9 @@
 import { Random as RandomLib } from "random";
 
 /**
- * A simple wrapper around Math.random(). Most apps need only this. For more
- * complex needs check {@link RandomLibDep}.
+ * A simple wrapper around Math.random().
+ *
+ * For more complex needs check {@link RandomLibDep}.
  *
  * ### Example
  *