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

package/src/Cache.ts

@@ -0,0 +1,85 @@
+/**
+ * 🗄️ Generic cache interface and LRU cache implementation.
+ *
+ * @module
+ */
+
+import { PositiveInt } from "./Type.js";
+
+/**
+ * Generic cache interface providing basic key-value storage operations.
+ *
+ * Keys are compared by reference (standard Map semantics).
+ *
+ * Note: Cache does not extend Map because eviction policies (like in LRU)
+ * violate the Liskov Substitution Principle.
+ */
+export interface Cache<K, V> {
+  /** Checks if a key exists in the cache. */
+  has: (key: K) => boolean;
+
+  /** Retrieves the value for a key, or undefined if not present. */
+  get: (key: K) => V | undefined;
+
+  /** Stores a key-value pair in the cache. */
+  set: (key: K, val: V) => void;
+
+  /** Removes a key from the cache. */
+  delete: (key: K) => void;
+
+  /** Returns a readonly view of the internal Map. */
+  readonly map: ReadonlyMap<K, V>;
+}
+
+/**
+ * Creates a Least Recently Used (LRU) cache with a maximum capacity.
+ *
+ * When the cache reaches capacity, the least recently used entry is evicted.
+ * Both `get` and `set` operations update the access order.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const cache = createLruCache<string, number>(2);
+ * cache.set("a", 1);
+ * cache.set("b", 2);
+ * cache.set("c", 3); // Evicts "a"
+ * cache.has("a"); // false
+ * ```
+ */
+export const createLruCache = <K, V>(capacity: PositiveInt): Cache<K, V> => {
+  const internalMap = new Map<K, V>();
+
+  return {
+    has: (key) => internalMap.has(key),
+
+    get: (key) => {
+      const value = internalMap.get(key);
+      if (value === undefined) return undefined;
+
+      // Move to end (most recently used)
+      internalMap.delete(key);
+      internalMap.set(key, value);
+      return value;
+    },
+
+    set: (key, val) => {
+      // If key exists, delete it first to update order
+      if (internalMap.has(key)) {
+        internalMap.delete(key);
+      } else if (internalMap.size === capacity) {
+        // Evict least recently used (first entry)
+        const firstKey = internalMap.keys().next().value as K;
+        internalMap.delete(firstKey);
+      }
+
+      internalMap.set(key, val);
+    },
+
+    delete: (key) => {
+      internalMap.delete(key);
+    },
+
+    map: internalMap,
+  };
+};

package/src/Evolu/Db.ts

@@ -31,12 +31,12 @@ import {
   AppOwner,
   createAppOwner,
   createOwnerSecret,
-  createWebSocketTransportConfig,
+  createOwnerWebSocketTransport,
   mnemonicToOwnerSecret,
   OwnerEncryptionKey,
   OwnerId,
+  OwnerTransport,
   OwnerWriteKey,
-  TransportConfig,
 } from "./Owner.js";
 import { ProtocolError, protocolVersion } from "./Protocol.js";
 import {
@@ -52,6 +52,7 @@ import {
   getDbSchema,
   MutationChange,
 } from "./Schema.js";
+import { createBaseSqliteStorageTables } from "./Storage.js";
 import {
   applyLocalOnlyChange,
   Clock,
@@ -107,7 +108,7 @@ export interface DbConfig extends ConsoleConfig, TimestampConfig {
    * added and removed for any owner (including {@link AppOwner}) via
    * {@link Evolu#useOwner}.
    *
-   * Use {@link createWebSocketTransportConfig} to create WebSocket transport
+   * Use {@link createOwnerWebSocketTransport} to create WebSocket transport
    * configurations with proper URL formatting and {@link OwnerId} inclusion. The
    * {@link OwnerId} in the URL enables relay authentication, allowing relay
    * servers to control access (e.g., for paid tiers or private instances).
@@ -134,16 +135,16 @@ export interface DbConfig extends ConsoleConfig, TimestampConfig {
    * // to work offline before the app connects
    * transports: [];
    *
-   * // Using createWebSocketTransportConfig helper for relay authentication
+   * // Using createOwnerWebSocketTransport helper for relay authentication
    * transports: [
-   *   createWebSocketTransportConfig({
-   *     relayUrl: "ws://localhost:4000",
+   *   createOwnerWebSocketTransport({
+   *     url: "ws://localhost:4000",
    *     ownerId,
    *   }),
    * ];
    * ```
    */
-  readonly transports: ReadonlyArray<TransportConfig>;
+  readonly transports: ReadonlyArray<OwnerTransport>;
 
   /**
    * External AppOwner to use when creating Evolu instance. Use this when you
@@ -573,6 +574,9 @@ const initializeDb =
       if (!result.ok) return result;
     }
 
+    const result = createBaseSqliteStorageTables(deps);
+    if (!result.ok) return result;
+
     return ok();
   };
 

package/src/Evolu/LocalAuth.ts

@@ -10,9 +10,9 @@ import {
   OwnerWriteKey,
 } from "./Owner.js";
 
-/** 
- * Local authentication and authorization system for Evolu.
- * This is API is subject to change and not recommended for production use.
+/**
+ * Local authentication and authorization system for Evolu. This is API is
+ * subject to change and not recommended for production use.
  *
  * @experimental
  */
@@ -178,10 +178,22 @@ export const createLocalAuth = (
     return {
       ...newOptions,
       authenticationPrompt: {
-        title: replaceMessageTokens(newOptions.authenticationPrompt?.title ?? "", username),
-        cancel: replaceMessageTokens(newOptions.authenticationPrompt?.cancel ?? "", username),
-        subtitle: replaceMessageTokens(newOptions.authenticationPrompt?.subtitle ?? "", username),
-        description: replaceMessageTokens(newOptions.authenticationPrompt?.description ?? "", username),
+        title: replaceMessageTokens(
+          newOptions.authenticationPrompt?.title ?? "",
+          username,
+        ),
+        cancel: replaceMessageTokens(
+          newOptions.authenticationPrompt?.cancel ?? "",
+          username,
+        ),
+        subtitle: replaceMessageTokens(
+          newOptions.authenticationPrompt?.subtitle ?? "",
+          username,
+        ),
+        description: replaceMessageTokens(
+          newOptions.authenticationPrompt?.description ?? "",
+          username,
+        ),
       },
     };
   };

package/src/Evolu/Owner.ts

@@ -16,29 +16,12 @@ import {
   idToIdBytes,
   Mnemonic,
   NonNegativeInt,
+  PositiveInt,
 } from "../Type.js";
 import { getOrNull } from "../Result.js";
-
-/**
- * 32 bytes of cryptographic entropy used to derive {@link Owner} keys.
- *
- * Can be created using {@link createOwnerSecret} or converted from a
- * {@link Mnemonic} using {@link mnemonicToOwnerSecret}.
- */
-export const OwnerSecret = brand("OwnerSecret", Entropy32);
-export type OwnerSecret = typeof OwnerSecret.Type;
-
-/** Creates a {@link OwnerSecret}. */
-export const createOwnerSecret = (deps: RandomBytesDep): OwnerSecret =>
-  deps.randomBytes.create(32) as OwnerSecret;
-
-/** Converts an {@link OwnerSecret} to a {@link Mnemonic}. */
-export const ownerSecretToMnemonic = (secret: OwnerSecret): Mnemonic =>
-  bip39.entropyToMnemonic(secret, wordlist) as Mnemonic;
-
-/** Converts a {@link Mnemonic} to an {@link OwnerSecret}. */
-export const mnemonicToOwnerSecret = (mnemonic: Mnemonic): OwnerSecret =>
-  bip39.mnemonicToEntropy(mnemonic, wordlist) as OwnerSecret;
+import type { Timestamp } from "./Timestamp.js";
+import { TimestampBytes } from "./Timestamp.js";
+import type { Storage } from "./Storage.js";
 
 /**
  * The Owner represents ownership of data in Evolu. Every database change is
@@ -105,6 +88,27 @@ export type OwnerEncryptionKey = typeof OwnerEncryptionKey.Type;
 export const OwnerWriteKey = brand("OwnerWriteKey", Entropy16);
 export type OwnerWriteKey = typeof OwnerWriteKey.Type;
 
+/**
+ * 32 bytes of cryptographic entropy used to derive {@link Owner} keys.
+ *
+ * Can be created using {@link createOwnerSecret} or converted from a
+ * {@link Mnemonic} using {@link mnemonicToOwnerSecret}.
+ */
+export const OwnerSecret = brand("OwnerSecret", Entropy32);
+export type OwnerSecret = typeof OwnerSecret.Type;
+
+/** Creates a {@link OwnerSecret}. */
+export const createOwnerSecret = (deps: RandomBytesDep): OwnerSecret =>
+  deps.randomBytes.create(32) as OwnerSecret;
+
+/** Converts an {@link OwnerSecret} to a {@link Mnemonic}. */
+export const ownerSecretToMnemonic = (secret: OwnerSecret): Mnemonic =>
+  bip39.entropyToMnemonic(secret, wordlist) as Mnemonic;
+
+/** Converts a {@link Mnemonic} to an {@link OwnerSecret}. */
+export const mnemonicToOwnerSecret = (mnemonic: Mnemonic): OwnerSecret =>
+  bip39.mnemonicToEntropy(mnemonic, wordlist) as OwnerSecret;
+
 /** Creates a randomly generated {@link OwnerWriteKey}. */
 export const createOwnerWriteKey = (deps: RandomBytesDep): OwnerWriteKey =>
   deps.randomBytes.create(16) as OwnerWriteKey;
@@ -174,82 +178,6 @@ export const createAppOwner = (secret: OwnerSecret): AppOwner => ({
   ...createOwner(secret),
 });
 
-/**
- * Transport configuration for connecting to relays.
- *
- * Each {@link Owner} can specify one or more transports to connect to different
- * relays for data synchronization. Currently supports WebSocket transport, with
- * future support planned for Bluetooth, LocalNetwork, and other protocols.
- */
-export type TransportConfig = WebSocketTransportConfig;
-
-/**
- * WebSocket transport configuration for relay connections.
- *
- * Use {@link createWebSocketTransportConfig} to create a properly formatted URL
- * with {@link OwnerId}. The relay uses {@link parseOwnerIdFromUrl} to extract the
- * OwnerId from the query string.
- *
- * ### Authentication and Error Handling
- *
- * When a relay rejects a connection (invalid OwnerId, unauthorized owner, or
- * server error), the browser WebSocket API does not expose the specific HTTP
- * status code or reason - it only reports a generic connection failure. The
- * client automatically retries with exponential backoff and jitter, eventually
- * succeeding once the configuration or server issue is resolved.
- *
- * Legitimate clients will be properly configured with valid credentials, so
- * automatic retry is appropriate.
- *
- * @see {@link createWebSocketTransportConfig}
- * @see {@link parseOwnerIdFromUrl}
- */
-export interface WebSocketTransportConfig {
-  readonly type: "WebSocket";
-  readonly url: string;
-}
-
-/**
- * Creates a {@link WebSocketTransportConfig} for the given relay URL and
- * {@link OwnerId}.
- *
- * ### Example
- *
- * ```ts
- * const transport = createWebSocketTransportConfig({
- *   relayUrl: "wss://relay.evolu.dev",
- *   ownerId: owner.id,
- * });
- * // Result: { type: "WebSocket", url: "wss://relay.evolu.dev?ownerId=..." }
- * ```
- */
-export const createWebSocketTransportConfig = ({
-  relayUrl,
-  ownerId,
-}: {
-  readonly relayUrl: string;
-  readonly ownerId: OwnerId;
-}): WebSocketTransportConfig => ({
-  type: "WebSocket",
-  url: `${relayUrl}?ownerId=${ownerId}`,
-});
-
-/**
- * Extracts {@link OwnerId} from a URL query string.
- *
- * Parses the query string `?ownerId=...` and validates that the extracted value
- * is a valid {@link OwnerId}.
- *
- * ### Example
- *
- * ```ts
- * parseOwnerIdFromUrl("/sync?ownerId=_12345678abcdefgh");
- * // Returns: OwnerId or null
- * ```
- */
-export const parseOwnerIdFromUrl = (url: string | undefined): OwnerId | null =>
-  getOrNull(OwnerId.fromUnknown(url?.split("=")[1]));
-
 /**
  * An {@link Owner} for sharding data.
  *
@@ -263,13 +191,13 @@ export const parseOwnerIdFromUrl = (url: string | undefined): OwnerId | null =>
  */
 export interface ShardOwner extends Owner {
   readonly type: "ShardOwner";
-  readonly transports?: ReadonlyArray<TransportConfig>;
+  readonly transports?: ReadonlyArray<OwnerTransport>;
 }
 
 /** Creates a {@link ShardOwner} from an {@link OwnerSecret}. */
 export const createShardOwner = (
   secret: OwnerSecret,
-  transports?: ReadonlyArray<TransportConfig>,
+  transports?: ReadonlyArray<OwnerTransport>,
 ): ShardOwner => {
   return {
     type: "ShardOwner",
@@ -299,7 +227,7 @@ export const createShardOwner = (
 export const deriveShardOwner = (
   owner: AppOwner,
   path: NonEmptyReadonlyArray<string | number>,
-  transports?: ReadonlyArray<TransportConfig>,
+  transports?: ReadonlyArray<OwnerTransport>,
 ): ShardOwner => {
   const secret = createSlip21(owner.encryptionKey, path) as OwnerSecret;
 
@@ -313,7 +241,7 @@ export const deriveShardOwner = (
 /** An {@link Owner} for collaborative data with write access. */
 export interface SharedOwner extends Owner {
   readonly type: "SharedOwner";
-  readonly transports?: ReadonlyArray<TransportConfig>;
+  readonly transports?: ReadonlyArray<OwnerTransport>;
 }
 
 /**
@@ -325,7 +253,7 @@ export interface SharedOwner extends Owner {
  */
 export const createSharedOwner = (
   secret: OwnerSecret,
-  transports?: ReadonlyArray<TransportConfig>,
+  transports?: ReadonlyArray<OwnerTransport>,
 ): SharedOwner => {
   return {
     type: "SharedOwner",
@@ -343,7 +271,7 @@ export interface SharedReadonlyOwner {
   readonly type: "SharedReadonlyOwner";
   readonly id: OwnerId;
   readonly encryptionKey: EncryptionKey;
-  readonly transports?: ReadonlyArray<TransportConfig>;
+  readonly transports?: ReadonlyArray<OwnerTransport>;
 }
 
 /** Creates a {@link SharedReadonlyOwner} from a {@link SharedOwner}. */
@@ -355,3 +283,112 @@ export const createSharedReadonlyOwner = (
   encryptionKey: sharedOwner.encryptionKey,
   ...(sharedOwner.transports && { transports: sharedOwner.transports }),
 });
+
+/**
+ * Transport configuration for connecting to relays.
+ *
+ * Currently only WebSocket, in the future Bluetooth, LocalNetwork, etc.
+ */
+export type OwnerTransport = OwnerWebSocketTransport;
+
+/**
+ * WebSocket transport configuration.
+ *
+ * ### Authentication and Error Handling
+ *
+ * When a relay rejects a connection (invalid OwnerId, unauthorized owner, or
+ * server error), the browser WebSocket API does not expose the specific HTTP
+ * status code or reason - it only reports a generic connection failure. The
+ * client automatically retries with exponential backoff and jitter, eventually
+ * succeeding once the configuration or server issue is resolved.
+ *
+ * Legitimate clients will be properly configured with valid credentials, so
+ * automatic retry is OK.
+ *
+ * @see {@link createOwnerWebSocketTransport}
+ * @see {@link parseOwnerIdFromOwnerWebSocketTransportUrl}
+ */
+export interface OwnerWebSocketTransport {
+  readonly type: "WebSocket";
+  readonly url: string;
+}
+
+/**
+ * Creates an {@link OwnerWebSocketTransport} for the given relay URL and
+ * {@link OwnerId}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const transport = createOwnerWebSocketTransport({
+ *   url: "wss://relay.evolu.dev",
+ *   ownerId: owner.id,
+ * });
+ * // Result: { type: "WebSocket", url: "wss://relay.evolu.dev?ownerId=..." }
+ * ```
+ */
+export const createOwnerWebSocketTransport = (config: {
+  readonly url: string;
+  readonly ownerId: OwnerId;
+}): OwnerWebSocketTransport => ({
+  type: "WebSocket",
+  url: `${config.url}?ownerId=${config.ownerId}`,
+});
+
+/**
+ * Extracts {@link OwnerId} from an {@link OwnerWebSocketTransport} URL query
+ * string.
+ *
+ * Parses the query string `?ownerId=...` and validates that the extracted value
+ * is a valid {@link OwnerId}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * parseOwnerIdFromOwnerWebSocketTransportUrl(
+ *   "/sync?ownerId=_12345678abcdefgh",
+ * );
+ * // Returns: OwnerId or null
+ * ```
+ */
+export const parseOwnerIdFromOwnerWebSocketTransportUrl = (
+  url: string,
+): OwnerId | null => getOrNull(OwnerId.fromUnknown(url.split("=")[1]));
+
+/**
+ * Usage data for an {@link OwnerId}.
+ *
+ * Tracks data consumption to monitor usage patterns and enforce quotas if
+ * needed. Used by both relays and clients.
+ *
+ * Relays and clients must handle rate limiting, connection limits, and request
+ * throttling separately with in-memory state.
+ */
+export interface OwnerUsage {
+  /** The {@link Owner} this usage data belongs to. */
+  readonly ownerId: OwnerIdBytes;
+
+  /** Total bytes stored in the database. */
+  readonly storedBytes: PositiveInt;
+
+  /** Total bytes received. */
+  readonly receivedBytes: number;
+
+  /** Total bytes sent. */
+  readonly sentBytes: number;
+
+  /**
+   * The minimum {@link Timestamp}.
+   *
+   * Helps {@link Storage} choose faster algorithms.
+   */
+  readonly firstTimestamp: TimestampBytes | null;
+
+  /**
+   * The maximum {@link Timestamp}.
+   *
+   * Helps {@link Storage} choose faster algorithms. Free relays can use it to
+   * identify inactive accounts for cleanup or archival.
+   */
+  readonly lastTimestamp: TimestampBytes | null;
+}

package/src/Evolu/Relay.ts

@@ -3,13 +3,13 @@ import { ConsoleConfig, ConsoleDep } from "../Console.js";
 import { TimingSafeEqualDep } from "../Crypto.js";
 import { LazyValue } from "../Function.js";
 import { err, ok, Result } from "../Result.js";
-import { sql, SqliteError } from "../Sqlite.js";
+import { sql, SqliteDep, SqliteError } from "../Sqlite.js";
 import { SimpleName } from "../Type.js";
-import { OwnerId, OwnerWriteKey, TransportConfig } from "./Owner.js";
+import { OwnerId, OwnerTransport, OwnerWriteKey } from "./Owner.js";
 import { ProtocolInvalidDataError } from "./Protocol.js";
 import {
-  createSqliteStorageBase,
-  CreateSqliteStorageBaseOptions,
+  createBaseSqliteStorage,
+  CreateBaseSqliteStorageOptions,
   EncryptedDbChange,
   SqliteStorageDeps,
   Storage,
@@ -44,9 +44,9 @@ export interface RelayConfig extends ConsoleConfig {
    * this only controls relay access, not write permissions. Since all data is
    * encrypted on the relay, OwnerId exposure is safe.
    *
-   * Owners specify which relays to connect to via {@link TransportConfig}. In
+   * Owners specify which relays to connect to via {@link OwnerTransport}. In
    * WebSocket-based implementations, this check occurs before accepting the
-   * connection, with the OwnerId typically extracted from the URL path (e.g.,
+   * connection, with the OwnerId typically extracted from the URL Path (e.g.,
    * `ws://localhost:4000/<ownerId>`).
    *
    * ### Example
@@ -68,36 +68,11 @@ export interface RelayConfig extends ConsoleConfig {
 
 export const createRelaySqliteStorage =
   (deps: SqliteStorageDeps & TimingSafeEqualDep) =>
-  (options: CreateSqliteStorageBaseOptions): Result<Storage, SqliteError> => {
-    const sqliteStorageBase = createSqliteStorageBase(deps)(options);
-    if (!sqliteStorageBase.ok) return sqliteStorageBase;
-
-    for (const query of [
-      sql`
-        create table if not exists evolu_writeKey (
-          "ownerId" blob not null,
-          "writeKey" blob not null,
-          primary key ("ownerId")
-        )
-        strict;
-      `,
-
-      sql`
-        create table if not exists evolu_message (
-          "ownerId" blob not null,
-          "timestamp" blob not null,
-          "change" blob not null,
-          primary key ("ownerId", "timestamp")
-        )
-        strict;
-      `,
-    ]) {
-      const result = deps.sqlite.exec(query);
-      if (!result.ok) return result;
-    }
-
-    return ok({
-      ...sqliteStorageBase.value,
+  (options: CreateBaseSqliteStorageOptions): Storage => {
+    const sqliteStorageBase = createBaseSqliteStorage(deps)(options);
+
+    return {
+      ...sqliteStorageBase,
 
       /**
        * Lazily authorizes the initiator's {@link OwnerWriteKey} for the given
@@ -159,11 +134,10 @@ export const createRelaySqliteStorage =
       writeMessages: async (ownerId, messages) => {
         const result = deps.sqlite.transaction(() => {
           for (const message of messages) {
-            const insertTimestampResult =
-              sqliteStorageBase.value.insertTimestamp(
-                ownerId,
-                timestampToTimestampBytes(message.timestamp),
-              );
+            const insertTimestampResult = sqliteStorageBase.insertTimestamp(
+              ownerId,
+              timestampToTimestampBytes(message.timestamp),
+            );
             if (!insertTimestampResult.ok) return insertTimestampResult;
 
             const insertMessage = deps.sqlite.exec(sql`
@@ -207,18 +181,18 @@ export const createRelaySqliteStorage =
 
       deleteOwner: (ownerId) => {
         const result = deps.sqlite.transaction(() => {
-          const del1 = deps.sqlite.exec(sql`
+          const deleteWriteKey = deps.sqlite.exec(sql`
             delete from evolu_writeKey where ownerId = ${ownerId};
           `);
-          if (!del1.ok) return del1;
+          if (!deleteWriteKey.ok) return deleteWriteKey;
 
-          const del2 = deps.sqlite.exec(sql`
+          const deleteMessages = deps.sqlite.exec(sql`
             delete from evolu_message where ownerId = ${ownerId};
           `);
-          if (!del2.ok) return del2;
+          if (!deleteMessages.ok) return deleteMessages;
 
-          const del3 = sqliteStorageBase.value.deleteOwner(ownerId);
-          if (!del3) return err(null);
+          const deleteBaseOwner = sqliteStorageBase.deleteOwner(ownerId);
+          if (!deleteBaseOwner) return err(null);
 
           return ok();
         });
@@ -228,9 +202,39 @@ export const createRelaySqliteStorage =
         }
         return true;
       },
-    });
+    };
   };
 
+export const createRelayStorageTables = (
+  deps: SqliteDep,
+): Result<void, SqliteError> => {
+  for (const query of [
+    sql`
+      create table evolu_writeKey (
+        "ownerId" blob not null,
+        "writeKey" blob not null,
+        primary key ("ownerId")
+      )
+      strict;
+    `,
+
+    sql`
+      create table evolu_message (
+        "ownerId" blob not null,
+        "timestamp" blob not null,
+        "change" blob not null,
+        primary key ("ownerId", "timestamp")
+      )
+      strict;
+    `,
+  ]) {
+    const result = deps.sqlite.exec(query);
+    if (!result.ok) return result;
+  }
+
+  return ok();
+};
+
 export interface RelayLogger {
   readonly started: (enableLogging: boolean, port: number) => void;
   readonly storageError: (error: unknown) => void;