@evolu/common 6.0.1-preview.25 → 6.0.1-preview.26

package/src/Evolu/Timestamp.ts

@@ -114,9 +114,33 @@ 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.
+ *
+ * ### 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/
+ *
+ * ### 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,

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/ManyToManyMap.ts

@@ -22,9 +22,6 @@ import { assert } from "./Assert.js";
  * - `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:
  *

package/src/Result.ts

@@ -87,8 +87,8 @@
  * ### Naming Convention
  *
  * - For values: `const user = getUser()`
- * - For void operations: `const result = foo()` (unless it would clash)
- * - For clashes, suffix the name: `const saveResult = save()`
+ * - For a single void operation: `const result = foo()`
+ * - For multiple void operations: use descriptive names for all
  *
  * ```ts
  * const processUser = () => {
@@ -96,13 +96,20 @@
  *   const user = getUser();
  *   if (!user.ok) return user;
  *
- *   // void operation
+ *   // single void operation
  *   const result = saveToDatabase(user.value);
  *   if (!result.ok) return result;
  *
- *   // avoiding clash
- *   const deleteFromCacheResult = deleteFromCache();
- *   if (!deleteFromCacheResult.ok) return deleteFromCacheResult;
+ *   return ok();
+ * };
+ *
+ * const setupDatabase = () => {
+ *   // multiple void operations - use descriptive names
+ *   const baseTables = createBaseTables();
+ *   if (!baseTables.ok) return baseTables;
+ *
+ *   const relayTables = createRelayTables();
+ *   if (!relayTables.ok) return relayTables;
  *
  *   return ok();
  * };

package/src/Sqlite.ts

@@ -1,9 +1,18 @@
 import { Brand } from "./Brand.js";
+import { createLruCache } from "./Cache.js";
 import { ConsoleDep } from "./Console.js";
 import { EncryptionKey } from "./Crypto.js";
 import { createTransferableError, TransferableError } from "./Error.js";
 import { err, ok, Result, tryAsync, trySync } from "./Result.js";
-import { Null, Number, SimpleName, String, Uint8Array, union } from "./Type.js";
+import {
+  Null,
+  Number,
+  PositiveInt,
+  SimpleName,
+  String,
+  Uint8Array,
+  union,
+} from "./Type.js";
 import { IntentionalNever, Predicate } from "./Types.js";
 
 /**
@@ -294,7 +303,38 @@ export interface RawSql {
 
 export type SqlTemplateParam = SqliteValue | SqlIdentifier | RawSql;
 
-/** TODO: Docs. */
+/**
+ * Creates a safe SQL query using a tagged template literal.
+ *
+ * Parameters are automatically escaped and bound as SQLite values. Use
+ * `sql.identifier` for column/table names and `sql.raw` for unescaped SQL.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const id = 42;
+ * const name = "Alice";
+ *
+ * const result = sqlite.exec(sql`
+ *   select *
+ *   from users
+ *   where id = ${id} and name = ${name};
+ * `);
+ *
+ * // For identifiers
+ * const tableName = "users";
+ * sqlite.exec(sql`
+ *   create table ${sql.identifier(tableName)} (
+ *     "id" text primary key,
+ *     "name" text not null
+ *   );
+ * `);
+ *
+ * // For raw SQL (use with caution)
+ * const orderBy = "created_at desc";
+ * sqlite.exec(sql`select * from users order by ${sql.raw(orderBy)};`);
+ * ```
+ */
 export const sql = (
   strings: TemplateStringsArray,
   ...parameters: Array<SqlTemplateParam>
@@ -342,6 +382,29 @@ sql.prepared = (
   return { ...query, options: { prepare: true } };
 };
 
+/**
+ * Checks if a SQL string contains mutation keywords (insert, update, delete,
+ * etc.). Results are cached for performance.
+ */
+export const isSqlMutation: Predicate<string> = (sql) => {
+  /**
+   * Without cache, "insert 1_000_000" Storage test dropped from 57742
+   * inserts/sec to 34k. Regex we used was fast, but CodeQL flagged it as a
+   * potential ReDoS vulnerability, so manual comment removal was the only
+   * option. LRU cache restores performance.
+   */
+  const cached = isSqlMutationCache.get(sql);
+  if (cached !== undefined) return cached;
+
+  const result = isSqlMutationRegEx.test(removeSqlComments(sql));
+  isSqlMutationCache.set(sql, result);
+  return result;
+};
+
+const isSqlMutationCache = createLruCache<string, boolean>(
+  PositiveInt.orThrow(10_000),
+);
+
 const isSqlMutationRegEx = new RegExp(
   `\\b(${[
     "alter",
@@ -365,6 +428,9 @@ const isSqlMutationRegEx = new RegExp(
  * ReDoS vulnerabilities.
  */
 const removeSqlComments = (sql: string): string => {
+  // Fast path: if there are no comments, return the original string
+  if (!sql.includes("--")) return sql;
+
   let result = "";
   let i = 0;
 
@@ -390,9 +456,6 @@ const removeSqlComments = (sql: string): string => {
   return result;
 };
 
-export const isSqlMutation: Predicate<string> = (sql) =>
-  isSqlMutationRegEx.test(removeSqlComments(sql));
-
 export interface SqliteQueryPlanRow {
   id: number;
   parent: number;

package/src/Task.ts

@@ -216,6 +216,32 @@ const isAbortError = (error: unknown): error is AbortError =>
   error !== null &&
   (error as { type?: unknown }).type === "AbortError";
 
+// For React Native
+if (typeof AbortSignal.any !== "function") {
+  AbortSignal.any = function (signals: Array<AbortSignal>): AbortSignal {
+    const controller = new AbortController();
+
+    const onAbort = (event: Event) => {
+      controller.abort((event.target as AbortSignal).reason);
+      cleanup();
+    };
+
+    const cleanup = () => {
+      for (const s of signals) s.removeEventListener("abort", onAbort);
+    };
+
+    for (const s of signals) {
+      if (s.aborted) {
+        controller.abort(s.reason);
+        return controller.signal;
+      }
+      s.addEventListener("abort", onAbort);
+    }
+
+    return controller.signal;
+  };
+}
+
 /**
  * Combines user signal from context with an internal signal.
  *
@@ -304,6 +330,21 @@ export const toTask = <T, E>(
     ]);
   }) as Task<T, E>;
 
+// For React Native
+if (typeof AbortSignal.timeout !== "function") {
+  AbortSignal.timeout = function (ms: number): AbortSignal {
+    const controller = new AbortController();
+    const id = setTimeout(() => {
+      controller.abort();
+    }, ms);
+    // clear timeout if aborted early
+    controller.signal.addEventListener("abort", () => {
+      clearTimeout(id);
+    });
+    return controller.signal;
+  };
+}
+
 /**
  * Creates a {@link Task} that waits for the specified duration.
  *

package/src/Type.ts

@@ -253,7 +253,6 @@ export interface Type<
    *
    * - When you need to convert a validation result to a nullable value
    * - When the error is not important and you just want the value or nothing
-   * - APIs that expect `T | null`
    *
    * ### Example
    *
@@ -370,8 +369,6 @@ export interface Type<
   readonly ParentError: ParentError;
 
   /**
-   * Error | ParentError
-   *
    * ### Example
    *
    * ```ts
@@ -461,7 +458,7 @@ export type InferParentError<A extends AnyType> =
     : never;
 
 /**
- * Extracts all error types (Error | ParentError) from a {@link Type}.
+ * Extracts all error types from a {@link Type}.
  *
  * @category Utilities
  */
@@ -1150,7 +1147,7 @@ export const trimmed: BrandFactory<"Trimmed", string, TrimmedError> = (
 export interface TrimmedError extends TypeError<"Trimmed"> {}
 
 export const formatTrimmedError = createTypeErrorFormatter<TrimmedError>(
-  (error) => `The value ${error.value} is not trimmed.`,
+  (error) => `The value ${error.value} must be trimmed.`,
 );
 
 /**
@@ -1717,7 +1714,7 @@ export const idBytesToId = (idBytes: IdBytes): Id =>
   uint8ArrayToBase64Url(idBytes) as unknown as Id;
 
 /**
- * Positive number.
+ * Positive number (> 0).
  *
  * ### Example
  *
@@ -1740,11 +1737,11 @@ export const positive: BrandFactory<"Positive", number, PositiveError> = (
 export interface PositiveError extends TypeError<"Positive"> {}
 
 export const formatPositiveError = createTypeErrorFormatter<PositiveError>(
-  (error) => `The value ${error.value} is not positive.`,
+  (error) => `The value ${error.value} must be positive (> 0).`,
 );
 
 /**
- * Negative number.
+ * Negative number (< 0).
  *
  * ### Example
  *
@@ -1764,11 +1761,11 @@ export const negative: BrandFactory<"Negative", number, NegativeError> = (
 export interface NegativeError extends TypeError<"Negative"> {}
 
 export const formatNegativeError = createTypeErrorFormatter<NegativeError>(
-  (error) => `The value ${error.value} is not negative.`,
+  (error) => `The value ${error.value} must be negative (< 0).`,
 );
 
 /**
- * Non-positive number.
+ * Non-positive number (≤ 0).
  *
  * ### Example
  *
@@ -1797,7 +1794,7 @@ export const formatNonPositiveError =
   );
 
 /**
- * Non-negative number.
+ * Non-negative number (≥ 0).
  *
  * ### Example
  *
@@ -1862,7 +1859,7 @@ export const int: BrandFactory<"Int", number, IntError> = (parent) =>
 export interface IntError extends TypeError<"Int"> {}
 
 export const formatIntError = createTypeErrorFormatter<IntError>(
-  (error) => `The value ${error.value} is not an integer.`,
+  (error) => `The value ${error.value} must be an integer.`,
 );
 
 /**
@@ -2008,7 +2005,7 @@ export const nonNaN: BrandFactory<"NonNaN", number, NonNaNError> = (parent) =>
 export interface NonNaNError extends TypeError<"NonNaN"> {}
 
 export const formatNonNaNError = createTypeErrorFormatter<NonNaNError>(
-  (error) => `The value ${error.value} is NaN (not a number).`,
+  () => `The value must not be NaN.`,
 );
 
 /** @category Number */
@@ -2030,7 +2027,7 @@ export const finite: BrandFactory<"Finite", number, FiniteError> = (parent) =>
 export interface FiniteError extends TypeError<"Finite"> {}
 
 export const formatFiniteError = createTypeErrorFormatter<FiniteError>(
-  (error) => `The value ${error.value} is not finite.`,
+  (error) => `The value ${error.value} must be finite.`,
 );
 
 /**

package/src/Types.ts

@@ -79,7 +79,7 @@ export type NullablePartial<
 export type IntentionalNever = never;
 
 /**
- * String | number | bigint | boolean | undefined | null
+ * String, number, bigint, boolean, undefined, null
  *
  * https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types
  */

package/src/WebSocket.ts

@@ -4,7 +4,6 @@
  * @module
  */
 
-import { assertNoErrorInCatch } from "./Assert.js";
 import { constVoid } from "./Function.js";
 import { err, ok, Result } from "./Result.js";
 import { retry, RetryError, RetryOptions } from "./Task.js";
@@ -192,7 +191,7 @@ export const createWebSocket: CreateWebSocket = (
    * - Is rejected when a connection is closed.
    * - Is resolved when WebSocket is disposed().
    */
-  retry(
+  void retry(
     {
       ...defaultRetryOptions,
       ...retryOptions,
@@ -222,6 +221,7 @@ export const createWebSocket: CreateWebSocket = (
             ? { type: "WebSocketConnectionError", event }
             : { type: "WebSocketConnectError", event };
           onError?.(error);
+
           // Trigger reconnect only on WebSocketConnectError.
           if (error.type === "WebSocketConnectError") {
             resolve(err(error));
@@ -237,14 +237,10 @@ export const createWebSocket: CreateWebSocket = (
           onMessage?.(event.data as string | ArrayBuffer | Blob);
         };
       }),
-  )(reconnectController)
-    .then((result) => {
-      if (result.ok || result.error.type === "AbortError") return;
-      onError?.(result.error as WebSocketError);
-    })
-    .catch((error: unknown) => {
-      assertNoErrorInCatch("WebSocket retry", error);
-    });
+  )(reconnectController).then((result) => {
+    if (result.ok || result.error.type === "AbortError") return;
+    onError?.(result.error as WebSocketError);
+  });
 
   return {
     send: (data) => {

package/src/index.ts

@@ -3,6 +3,7 @@ export * from "./Assert.js";
 export * from "./BigInt.js";
 export * from "./Brand.js";
 export * from "./Buffer.js";
+export * from "./Cache.js";
 export * from "./CallbackRegistry.js";
 export * from "./Console.js";
 export * from "./Crypto.js";
@@ -10,6 +11,7 @@ export * from "./Eq.js";
 export * from "./Error.js";
 export * from "./Evolu/Public.js";
 export * from "./Function.js";
+export * from "./Identicon.js";
 export * from "./ManyToManyMap.js";
 export * from "./Number.js";
 export * from "./Object.js";