@evolu/common 5.4.8 → 6.0.0

package/src/Evolu/Sync.ts

@@ -0,0 +1,105 @@
+import { ConsoleConfig, ConsoleDep } from "../Console.js";
+import { createWebSocket } from "../WebSocket.js";
+import { ProtocolMessage } from "./Protocol.js";
+import { Millis } from "./Timestamp.js";
+
+export interface Sync {
+  readonly send: (message: ProtocolMessage) => void;
+}
+
+export interface SyncDep {
+  readonly sync: Sync;
+}
+
+export type CreateSync = (deps: ConsoleDep) => (config: SyncConfig) => Sync;
+
+export interface CreateSyncDep {
+  readonly createSync: CreateSync;
+}
+
+export interface SyncConfig extends ConsoleConfig {
+  readonly syncUrl: string;
+  readonly onOpen: (send: Sync["send"]) => void;
+  readonly onMessage: (message: Uint8Array, send: Sync["send"]) => void;
+}
+
+export const createWebSocketSync: CreateSync = (_deps) => (config) => {
+  const sync: Sync = {
+    send: (message) => {
+      /**
+       * We don't need an in-memory queue; apps can be offline for a long time,
+       * and mutations are stored in SQLite. Dropped CRDT messages are synced
+       * when the web socket connection is open.
+       */
+      if (socket.getReadyState() !== "open") return;
+      socket.send(message);
+    },
+  };
+
+  const socket = createWebSocket(config.syncUrl, {
+    binaryType: "arraybuffer",
+    onOpen: () => {
+      config.onOpen(sync.send);
+    },
+    onMessage: (data) => {
+      if (data instanceof ArrayBuffer) {
+        const messages = new Uint8Array(data);
+        config.onMessage(messages, sync.send);
+      }
+    },
+  });
+
+  return sync;
+};
+
+/**
+ * The possible states of a synchronization process. The `SyncState` can be one
+ * of the following:
+ *
+ * - {@link SyncStateInitial}
+ * - {@link SyncStateIsSyncing}
+ * - {@link SyncStateIsSynced}
+ * - {@link SyncStateIsNotSynced}
+ */
+export type SyncState =
+  | SyncStateInitial
+  | SyncStateIsSyncing
+  | SyncStateIsSynced
+  | SyncStateIsNotSynced;
+
+/**
+ * The initial synchronization state when the app starts. In this state, the app
+ * needs to determine whether the data is synced.
+ */
+export interface SyncStateInitial {
+  readonly type: "SyncStateInitial";
+}
+
+export interface SyncStateIsSyncing {
+  readonly type: "SyncStateIsSyncing";
+}
+
+export interface SyncStateIsSynced {
+  readonly type: "SyncStateIsSynced";
+  readonly time: Millis;
+}
+
+export interface SyncStateIsNotSynced {
+  readonly type: "SyncStateIsNotSynced";
+  readonly error: NetworkError | ServerError | PaymentRequiredError;
+}
+
+export interface NetworkError {
+  readonly type: "NetworkError";
+}
+
+export interface ServerError {
+  readonly type: "ServerError";
+  readonly status: number;
+}
+
+export interface PaymentRequiredError {
+  readonly type: "PaymentRequiredError";
+}
+
+export const initialSyncState: SyncStateInitial = { type: "SyncStateInitial" };

package/src/Evolu/Timestamp.ts

@@ -0,0 +1,311 @@
+import { assert } from "../Assert.js";
+import { NanoIdLibDep } from "../NanoId.js";
+import { increment } from "../Number.js";
+import { Order, orderUint8Array } from "../Order.js";
+import { err, getOrThrow, ok, Result } from "../Result.js";
+import { TimeDep } from "../Time.js";
+import {
+  brand,
+  lessThanOrEqualTo,
+  NonNegativeInt,
+  object,
+  regex,
+  String,
+} from "../Type.js";
+import { Brand } from "../Types.js";
+
+export interface TimestampConfig {
+  /**
+   * Maximum physical clock drift allowed in ms.
+   *
+   * The default value is 5 * 60 * 1000 (5 minutes).
+   */
+  readonly maxDrift: number;
+}
+
+export interface TimestampConfigDep {
+  readonly timestampConfig: TimestampConfig;
+}
+
+export type TimestampError =
+  | TimestampDriftError
+  | TimestampCounterOverflowError
+  | TimestampDuplicateNodeError
+  | TimestampTimeOutOfRangeError;
+
+export interface TimestampDriftError {
+  readonly type: "TimestampDriftError";
+  readonly next: Millis;
+  readonly now: Millis;
+}
+
+export interface TimestampCounterOverflowError {
+  readonly type: "TimestampCounterOverflowError";
+}
+
+export interface TimestampDuplicateNodeError {
+  readonly type: "TimestampDuplicateNodeError";
+  readonly nodeId: NodeId;
+}
+
+export interface TimestampTimeOutOfRangeError {
+  readonly type: "TimestampTimeOutOfRangeError";
+}
+
+/**
+ * Millis is a timestamp in milliseconds, like `Date.now()`, but limited to the
+ * maximum value representable in 6 bytes (281474976710655) minus 1 (reserved
+ * for infinity). This enables more efficient binary serialization, saving 2
+ * bytes compared to the typical 8-byte (64-bit) timestamp representation.
+ *
+ * This limit is enforced to prevent data corruption. If a device's clock
+ * exceeds this range, Evolu will stop saving data until the clock is
+ * corrected.
+ *
+ * `new Date(281474976710654).toString()` = Tue Aug 02 10889 07:31:49
+ */
+export const Millis = brand(
+  "Millis",
+  lessThanOrEqualTo(281474976710655 - 1)(NonNegativeInt),
+);
+export type Millis = typeof Millis.Type;
+
+export const minMillis = 0 as Millis;
+export const maxMillis = (281474976710655 - 1) as Millis;
+
+export const Counter = brand(
+  "Counter",
+  lessThanOrEqualTo(65535)(NonNegativeInt),
+);
+export type Counter = typeof Counter.Type;
+
+export const minCounter = 0 as Counter;
+export const maxCounter = 65535 as Counter;
+
+/**
+ * A NodeId uniquely identifies an owner's device. Generated once per device
+ * using cryptographic randomness.
+ *
+ * Collision probability (birthday paradox):
+ *
+ * - 1,000 devices: ~0.00000000000271% (negligible).
+ * - 1M devices: ~0.00000271% (1 in 37M chance).
+ * - 135M devices: ~1% chance.
+ * - 4.29B devices: ~50% chance.
+ *
+ * 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?
+ *
+ * If the device belongs to a different owner, nothing will happen because
+ * different owner have different owner IDs. Timestamps are partitioned by
+ * OwnerId.
+ *
+ * If the device belongs to the same owner, the other device will return
+ * {@link TimestampDuplicateNodeError}.
+ */
+export const NodeId = regex("NodeId", /^[a-f0-9]{16}$/)(String);
+export type NodeId = typeof NodeId.Type;
+
+export const minNodeId = "0000000000000000" as NodeId;
+export const maxNodeId = "ffffffffffffffff" as NodeId;
+
+/**
+ * Hybrid Logical Clock timestamp.
+ *
+ * - 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/
+ */
+export const Timestamp = object({
+  millis: Millis,
+  counter: Counter,
+  nodeId: NodeId,
+});
+export type Timestamp = typeof Timestamp.Type;
+
+export const createTimestamp = ({
+  millis = minMillis,
+  counter = minCounter,
+  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;
+  return createTimestamp({ nodeId });
+};
+
+/** TimestampString is a sortable string version of {@link Timestamp}. */
+export type TimestampString = string & Brand<"TimestampString">;
+
+export const timestampToTimestampString = (t: Timestamp): TimestampString =>
+  [
+    new Date(t.millis).toISOString(),
+    t.counter.toString(16).toUpperCase().padStart(4, "0"),
+    t.nodeId,
+  ].join("-") as TimestampString;
+
+export const timestampStringToTimestamp = (
+  timestampString: TimestampString,
+): Timestamp => {
+  const array = timestampString.split("-");
+  const timestamp = {
+    millis: Date.parse(array.slice(0, 3).join("-")).valueOf(),
+    counter: parseInt(array[3], 16),
+    nodeId: array[4],
+  };
+  assert(Timestamp.is(timestamp), "timestampString is malformed");
+  return timestamp;
+};
+
+const getNextMillis =
+  (deps: TimeDep & TimestampConfigDep) =>
+  (
+    millis: ReadonlyArray<Millis>,
+  ): Result<Millis, TimestampTimeOutOfRangeError | TimestampDriftError> => {
+    const now = Millis.from(deps.time.now());
+    if (!now.ok) {
+      return err({ type: "TimestampTimeOutOfRangeError" });
+    }
+    const next = Math.max(now.value, ...millis) as Millis;
+    return next - now.value > deps.timestampConfig.maxDrift
+      ? err<TimestampDriftError>({
+          type: "TimestampDriftError",
+          now: now.value,
+          next,
+        })
+      : ok(next);
+  };
+
+const incrementCounter = (
+  counter: Counter,
+): Result<Counter, TimestampCounterOverflowError> => {
+  const next = Counter.from(increment(counter));
+  if (!next.ok) return err({ type: "TimestampCounterOverflowError" });
+  return ok(next.value);
+};
+
+export const sendTimestamp =
+  (deps: TimeDep & TimestampConfigDep) =>
+  (
+    timestamp: Timestamp,
+  ): Result<
+    Timestamp,
+    | TimestampDriftError
+    | TimestampCounterOverflowError
+    | TimestampTimeOutOfRangeError
+  > => {
+    const millis = getNextMillis(deps)([timestamp.millis]);
+    if (!millis.ok) return millis;
+
+    const counter =
+      millis.value === timestamp.millis
+        ? incrementCounter(timestamp.counter)
+        : ok(minCounter);
+    if (!counter.ok) return counter;
+
+    return ok({
+      millis: millis.value,
+      counter: counter.value,
+      nodeId: timestamp.nodeId,
+    });
+  };
+
+export const receiveTimestamp =
+  (deps: TimeDep & TimestampConfigDep) =>
+  (
+    local: Timestamp,
+    remote: Timestamp,
+  ): Result<
+    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;
+
+    const counter =
+      millis.value === local.millis && millis.value === remote.millis
+        ? incrementCounter(Math.max(local.counter, remote.counter) as Counter)
+        : millis.value === local.millis
+          ? incrementCounter(local.counter)
+          : millis.value === remote.millis
+            ? incrementCounter(remote.counter)
+            : ok(minCounter);
+
+    if (!counter.ok) return counter;
+
+    return ok({
+      millis: millis.value,
+      counter: counter.value,
+      nodeId: local.nodeId,
+    });
+  };
+
+/** BinaryTimestamp is a binary and sortable version of {@link Timestamp} for DB. */
+export type BinaryTimestamp = Uint8Array & Brand<"BinaryTimestamp">;
+
+export const binaryTimestampLength = getOrThrow(NonNegativeInt.from(16));
+
+export const timestampToBinaryTimestamp = (
+  timestamp: Timestamp,
+): BinaryTimestamp => {
+  const { millis, counter, nodeId } = timestamp;
+
+  // 6 bytes for millis, 2 bytes for counter, 8 bytes for nodeId.
+  const value = new Uint8Array(16);
+
+  // Encode `millis` into the first 6 bytes.
+  const millisBigInt = BigInt(millis);
+  value[0] = Number((millisBigInt >> 40n) & 0xffn);
+  value[1] = Number((millisBigInt >> 32n) & 0xffn);
+  value[2] = Number((millisBigInt >> 24n) & 0xffn);
+  value[3] = Number((millisBigInt >> 16n) & 0xffn);
+  value[4] = Number((millisBigInt >> 8n) & 0xffn);
+  value[5] = Number(millisBigInt & 0xffn);
+
+  // Encode `counter` into the next 2 bytes.
+  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;
+  }
+
+  return value as BinaryTimestamp;
+};
+
+export const binaryTimestampToTimestamp = (
+  timestamp: BinaryTimestamp,
+): Timestamp => {
+  // Decode `millis` from the first 6 bytes.
+  const millis =
+    (BigInt(timestamp[0]) << 40n) |
+    (BigInt(timestamp[1]) << 32n) |
+    (BigInt(timestamp[2]) << 24n) |
+    (BigInt(timestamp[3]) << 16n) |
+    (BigInt(timestamp[4]) << 8n) |
+    BigInt(timestamp[5]);
+
+  // Decode `counter` from the next 2 bytes.
+  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");
+  }
+
+  return { millis: Number(millis), counter, nodeId } as Timestamp;
+};
+
+export const orderBinaryTimestamp: Order<BinaryTimestamp> = orderUint8Array;

package/src/Function.ts

@@ -0,0 +1,58 @@
+/**
+ * Helper function to ensure exhaustive matching in a switch statement. Throws
+ * an error if an unhandled case is encountered.
+ *
+ * Remember, it's useful only when we don't return anything from the switch
+ * statement. Otherwise, a return type of a function is enough.
+ *
+ * ### Example
+ *
+ * ```ts
+ * type Color = "red" | "green" | "blue";
+ *
+ * function handleColor(color: Color): void {
+ *   switch (color) {
+ *     case "red":
+ *       console.log("Handling red");
+ *       break;
+ *     case "green":
+ *       console.log("Handling green");
+ *       break;
+ *     case "blue":
+ *       console.log("Handling blue");
+ *       break;
+ *     default:
+ *       exhaustiveCheck(color); // Ensures all cases are handled
+ *   }
+ * }
+ * ```
+ */
+export const exhaustiveCheck = (value: never): never => {
+  throw new Error(`exhaustiveCheck unhandled case: ${JSON.stringify(value)}`);
+};
+
+export const identity = <A>(a: A): A => a;
+
+/**
+ * A function that delays computation and returns a value of type T.
+ *
+ * Useful for:
+ *
+ * - Lazy evaluation
+ * - Returning constant values
+ * - Providing default or placeholder behaviors
+ *
+ * ### Example
+ *
+ * ```ts
+ * const getRandomNumber: LazyValue<number> = () => Math.random();
+ * const randomValue = getRandomNumber();
+ * ```
+ */
+export type LazyValue<T> = () => T;
+
+export const constVoid: LazyValue<void> = () => undefined;
+export const constUndefined: LazyValue<undefined> = () => undefined;
+export const constNull: LazyValue<null> = () => null;
+export const constTrue: LazyValue<true> = () => true;
+export const constFalse: LazyValue<false> = () => false;

package/src/ManyToManyMap.ts

@@ -0,0 +1,140 @@
+/** Represents a many-to-many mapping between keys and values. */
+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. */
+  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;
+
+  /** 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;
+
+  /** Checks if a value exists in the map. */
+  hasValue: (value: V) => boolean;
+
+  /** Deletes all associations for a key. */
+  deleteKey: (key: K) => boolean;
+
+  /** Deletes all associations for a value. */
+  deleteValue: (value: V) => boolean;
+
+  /** Clears all associations in the map. */
+  clear(): void;
+}
+
+/** 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>>();
+
+  const map: ManyToManyMap<K, V> = {
+    add(key: K, value: V) {
+      let values = forwardMap.get(key);
+      if (!values) {
+        values = new Set<V>();
+        forwardMap.set(key, values);
+      }
+      values.add(value);
+
+      let keys = reverseMap.get(value);
+      if (!keys) {
+        keys = new Set<K>();
+        reverseMap.set(value, keys);
+      }
+      keys.add(key);
+
+      return map;
+    },
+
+    remove(key: K, value: V) {
+      const values = forwardMap.get(key);
+      if (!values?.has(value)) return false;
+
+      values.delete(value);
+      if (values.size === 0) {
+        forwardMap.delete(key);
+      }
+
+      const keys = reverseMap.get(value);
+      if (keys?.size) {
+        keys.delete(key);
+        if (keys.size === 0) {
+          reverseMap.delete(value);
+        }
+      }
+
+      return true;
+    },
+
+    getValues(key: K) {
+      return forwardMap.get(key);
+    },
+
+    getKeys(value: V) {
+      return reverseMap.get(value);
+    },
+
+    hasPair(key: K, value: V) {
+      const values = forwardMap.get(key);
+      return values?.has(value) ?? false;
+    },
+
+    hasKey(key: K) {
+      return forwardMap.has(key);
+    },
+
+    hasValue(value: V) {
+      return reverseMap.has(value);
+    },
+
+    deleteKey(key: K) {
+      const values = forwardMap.get(key);
+      if (!values) return false;
+
+      for (const value of values) {
+        const keys = reverseMap.get(value);
+        if (keys) {
+          keys.delete(key);
+          if (keys.size === 0) {
+            reverseMap.delete(value);
+          }
+        }
+      }
+      forwardMap.delete(key);
+      return true;
+    },
+
+    deleteValue(value: V) {
+      const keys = reverseMap.get(value);
+      if (!keys) return false;
+
+      for (const key of keys) {
+        const values = forwardMap.get(key);
+        if (values) {
+          values.delete(value);
+          if (values.size === 0) {
+            forwardMap.delete(key);
+          }
+        }
+      }
+      reverseMap.delete(value);
+      return true;
+    },
+
+    clear() {
+      forwardMap.clear();
+      reverseMap.clear();
+    },
+  };
+
+  return map;
+};

package/src/NanoId.ts

@@ -0,0 +1,39 @@
+import { customAlphabet, nanoid, urlAlphabet } from "nanoid";
+
+/**
+ * Interface representing a NanoId library.
+ *
+ * It's useful for testing by allowing ID generation to be mocked, ensuring
+ * consistent results.
+ *
+ * @see https://github.com/ai/nanoid
+ *
+ * ### Example
+ *
+ * ```ts
+ * const foo = createFoo({
+ *   ...createNanoIdLib(),
+ *   ...createTime(),
+ * });
+ * ```
+ */
+export interface NanoIdLib {
+  readonly urlAlphabet: string;
+
+  readonly customAlphabet: (
+    alphabet: string,
+    defaultSize?: number,
+  ) => (size?: number) => string;
+
+  readonly nanoid: (size?: number) => string;
+}
+
+export interface NanoIdLibDep {
+  readonly nanoIdLib: NanoIdLib;
+}
+
+export const createNanoIdLib = (): NanoIdLib => ({
+  urlAlphabet,
+  customAlphabet,
+  nanoid,
+});