@evolu/common 7.2.1 → 7.2.3

package/src/local-first/Sync.ts

@@ -1,10 +1,11 @@
 import {
+  appendToArray,
   firstInArray,
   isNonEmptyReadonlyArray,
   NonEmptyArray,
   NonEmptyReadonlyArray,
 } from "../Array.js";
-import { assert } from "../Assert.js";
+import { assert, assertNonEmptyReadonlyArray } from "../Assert.js";
 import { Brand } from "../Brand.js";
 import { ConsoleDep } from "../Console.js";
 import {
@@ -15,7 +16,7 @@ import {
 import { eqArrayNumber } from "../Eq.js";
 import { createTransferableError, TransferableError } from "../Error.js";
 import { constFalse, constTrue } from "../Function.js";
-import { objectToEntries } from "../Object.js";
+import { createRecord, objectToEntries } from "../Object.js";
 import { RandomDep } from "../Random.js";
 import { createResources } from "../Resources.js";
 import { err, ok, Result } from "../Result.js";
@@ -26,12 +27,12 @@ import {
   sqliteBooleanToBoolean,
   SqliteDep,
   SqliteError,
-  sqliteFalse,
   SqliteValue,
 } from "../Sqlite.js";
 import { AbortError, createMutex } from "../Task.js";
 import { TimeDep } from "../Time.js";
 import {
+  Boolean,
   DateIso,
   IdBytes,
   idBytesToId,
@@ -42,16 +43,12 @@ import { CreateWebSocketDep, WebSocket } from "../WebSocket.js";
 import type { AppOwnerDep, PostMessageDep } from "./Db.js";
 import {
   AppOwner,
-  OwnerEncryptionKey,
+  Owner,
   OwnerId,
-  OwnerIdBytes,
   ownerIdBytesToOwnerId,
   ownerIdToOwnerIdBytes,
   OwnerTransport,
-  OwnerWriteKey,
-  ShardOwner,
-  SharedOwner,
-  SharedReadonlyOwner,
+  ReadonlyOwner,
 } from "./Owner.js";
 import {
   applyProtocolMessageAsClient,
@@ -74,7 +71,6 @@ import {
   getOwnerUsage,
   getTimestampInsertStrategy,
   Storage,
-  StorageInsertTimestampStrategy,
   StorageWriteError,
   updateOwnerUsage,
 } from "./Storage.js";
@@ -97,9 +93,9 @@ export interface Sync extends Disposable {
   /**
    * Assigns or removes an owner to/from transports with reference counting.
    *
-   * Owners are only "active" if assigned to at least one transport. Uses
-   * `owner.transports` or falls back to config transports. Multiple calls
-   * increment/decrement reference counts (useful for React Hooks).
+   * Owners are only synced if assigned to at least one transport. Uses
+   * `owner.transports` or falls back to {@link SyncConfig} transports. Multiple
+   * calls increment/decrement reference counts (useful for React Hooks).
    */
   readonly useOwner: (use: boolean, owner: SyncOwner) => void;
 
@@ -119,18 +115,13 @@ export interface SyncDep {
 }
 
 /**
- * Represents an owner for sync operations. This is a unified interface that
- * abstracts over the specific owner types ({@link ShardOwner},
- * {@link SharedOwner}, {@link SharedReadonlyOwner}) for the sync layer.
+ * Represents an owner for sync operations.
  *
- * The sync layer only needs the essential data for synchronization and doesn't
- * need to distinguish between different owner types.
+ * Includes readonly owner fields plus optional write key (for clients that
+ * write) and optional transports to override SyncConfig transports per owner.
  */
-export interface SyncOwner {
-  readonly id: OwnerId;
-  readonly encryptionKey: OwnerEncryptionKey;
-  /** Optional for read-only owners like {@link SharedReadonlyOwner}. */
-  readonly writeKey?: OwnerWriteKey;
+export interface SyncOwner extends ReadonlyOwner {
+  readonly writeKey?: Owner["writeKey"];
   readonly transports?: ReadonlyArray<OwnerTransport>;
 }
 
@@ -180,7 +171,7 @@ export const createSync =
     /** Returns owner data only if actively assigned to at least one transport. */
     const getSyncOwner = (ownerId: OwnerId): SyncOwner | null => {
       if (isDisposed) return null;
-      return transports.getConsumer(ownerId);
+      return resources.getConsumer(ownerId);
     };
 
     const storageResult = createClientStorage({
@@ -191,24 +182,24 @@ export const createSync =
     if (!storageResult.ok) return storageResult;
     const storage = storageResult.value;
 
-    const createResource = (transportConfig: OwnerTransport): WebSocket => {
-      const transportKey = createTransportKey(transportConfig);
+    const createResource = (transport: OwnerTransport): WebSocket => {
+      const transportKey = createTransportKey(transport);
 
       deps.console.log("[sync]", "createWebSocket", {
         transportKey,
-        url: transportConfig.url,
+        url: transport.url,
       });
 
-      return deps.createWebSocket(transportConfig.url, {
+      return deps.createWebSocket(transport.url, {
         binaryType: "arraybuffer",
 
         onOpen: () => {
           if (isDisposed) return;
 
-          const webSocket = transports.getResource(transportKey);
+          const webSocket = resources.getResource(transportKey);
           if (!webSocket) return;
 
-          const ownerIds = transports.getConsumersForResource(transportKey);
+          const ownerIds = resources.getConsumersForResource(transportKey);
           deps.console.log("[sync]", "onOpen", { transportKey, ownerIds });
 
           for (const ownerId of ownerIds) {
@@ -239,7 +230,7 @@ export const createSync =
           // Only handle ArrayBuffer data for sync messages
           if (isDisposed || !(data instanceof ArrayBuffer)) return;
 
-          const webSocket = transports.getResource(transportKey);
+          const webSocket = resources.getResource(transportKey);
           if (!webSocket) return;
 
           const input = new Uint8Array(data);
@@ -277,7 +268,7 @@ export const createSync =
       });
     };
 
-    const transports = createResources<
+    const resources = createResources<
       WebSocket,
       TransportKey,
       OwnerTransport,
@@ -327,16 +318,16 @@ export const createSync =
         }
 
         deps.console.log("[sync]", "useOwner", { use, owner });
-        const transportsToUse = owner.transports ?? config.transports;
+        const transports = owner.transports ?? config.transports;
 
         if (use) {
-          transports.addConsumer(owner, transportsToUse);
+          resources.addConsumer(owner, transports);
         } else {
-          const result = transports.removeConsumer(owner, transportsToUse);
+          const result = resources.removeConsumer(owner, transports);
 
           if (!result.ok) {
             deps.console.warn("[sync]", "Failed to remove consumer", {
-              transportsToUse,
+              transports,
               ownerId: owner.id,
               error: result.error,
             });
@@ -382,13 +373,13 @@ export const createSync =
             messages,
           );
 
-          const transportsToUse = owner.transports ?? config.transports;
+          const transports = owner.transports ?? config.transports;
 
           // Send message to all transports for this owner
-          for (const transportConfig of transportsToUse) {
-            const transportKey = createTransportKey(transportConfig);
+          for (const transport of transports) {
+            const transportKey = createTransportKey(transport);
 
-            const webSocket = transports.getResource(transportKey);
+            const webSocket = resources.getResource(transportKey);
             if (!webSocket) continue;
 
             if (webSocket.isOpen()) {
@@ -404,7 +395,7 @@ export const createSync =
       [Symbol.dispose]: () => {
         if (isDisposed) return;
         isDisposed = true;
-        transports[Symbol.dispose]();
+        resources[Symbol.dispose]();
       },
     };
 
@@ -459,8 +450,7 @@ const createClientStorage =
       SqliteDep &
       SymmetricCryptoDep &
       TimeDep &
-      TimestampConfigDep &
-      PostMessageDep,
+      TimestampConfigDep,
   ) =>
   (config: {
     onError: (
@@ -553,12 +543,6 @@ const createClientStorage =
               if (!applyMessagesResult.ok) return applyMessagesResult;
             }
 
-            // // Apply local mutations atomically with approved messages
-            // for (const change of localMutations) {
-            //   const result = applyLocalOnlyChange(deps)(change);
-            //   if (!result.ok) return result;
-            // }
-
             return deps.clock.save(clockTimestamp);
           });
 
@@ -600,11 +584,11 @@ const createClientStorage =
         }
 
         const { rows } = result.value;
-        assert(rows.length > 0, "Rows must not be empty");
+        assertNonEmptyReadonlyArray(rows, "Every timestamp must have rows");
 
-        const { table, id } = rows[0];
-        const values: Record<string, SqliteValue> = {};
-        let isInsert = false;
+        const { table, id } = firstInArray(rows);
+        const values = createRecord<string, SqliteValue>();
+        let isInsert;
         let isDelete: boolean | null = null;
 
         for (const r of rows) {
@@ -614,10 +598,13 @@ const createClientStorage =
             case "createdAt":
               isInsert = true;
               break;
+            case "updatedAt":
+              isInsert = false;
+              break;
             case "isDeleted":
               assert(
                 SqliteBoolean.is(r.value),
-                "isDeleted column must contain a valid SqliteBoolean (0 or 1)",
+                "isDeleted column must contain a valid SqliteBoolean",
               );
               isDelete = sqliteBooleanToBoolean(r.value);
               break;
@@ -626,6 +613,8 @@ const createClientStorage =
           }
         }
 
+        assert(Boolean.is(isInsert), "isInsert must be in evolu_history");
+
         const message: CrdtMessage = {
           timestamp: timestampBytesToTimestamp(timestamp),
           change: DbChange.orThrow({
@@ -646,9 +635,27 @@ const createClientStorage =
 
 type TransportKey = string & Brand<"TransportKey">;
 
-/** Creates a unique identifier for a transport configuration. */
-const createTransportKey = (transportConfig: OwnerTransport): TransportKey => {
-  return `${transportConfig.type}:${transportConfig.url}` as TransportKey;
+/** Creates a unique identifier for a {@link OwnerTransport}. */
+const createTransportKey = (transport: OwnerTransport): TransportKey => {
+  return `${transport.type}:${transport.url}` as TransportKey;
+};
+
+const dbChangeToColumns = (change: DbChange, now: DateIso) => {
+  let values = objectToEntries(change.values);
+
+  // SystemColumns are not encoded in change.values.
+  values = appendToArray(values, [
+    change.isInsert ? "createdAt" : "updatedAt",
+    now,
+  ]);
+  if (change.isDelete != null) {
+    values = appendToArray(values, [
+      "isDeleted",
+      booleanToSqliteBoolean(change.isDelete),
+    ]);
+  }
+
+  return values;
 };
 
 export const applyLocalOnlyChange =
@@ -661,23 +668,16 @@ export const applyLocalOnlyChange =
       `);
       if (!result.ok) return result;
     } else {
-      const now = deps.time.nowIso();
       const ownerId = deps.appOwner.id;
+      const columns = dbChangeToColumns(change, deps.time.nowIso());
 
-      let entries = objectToEntries(change.values);
-      if (change.isDelete !== null) {
-        entries = [...entries, ["isDeleted", sqliteFalse]];
-      }
-
-      for (const [column, value] of entries) {
+      for (const [column, value] of columns) {
         const result = deps.sqlite.exec(sql.prepared`
           insert into ${sql.identifier(change.table)}
-            ("ownerId", "id", ${sql.identifier(column)}, createdAt, updatedAt)
-          values (${ownerId}, ${change.id}, ${value}, ${now}, ${now})
+            ("ownerId", "id", ${sql.identifier(column)})
+          values (${ownerId}, ${change.id}, ${value})
           on conflict ("ownerId", "id") do update
-            set
-              ${sql.identifier(column)} = ${value},
-              updatedAt = ${now};
+            set ${sql.identifier(column)} = ${value};
         `);
         if (!result.ok) return result;
       }
@@ -694,35 +694,75 @@ const applyMessages =
   ): Result<void, SqliteError> => {
     const ownerIdBytes = ownerIdToOwnerIdBytes(ownerId);
 
-    const usageResult = getOwnerUsage(deps)(
+    const usage = getOwnerUsage(deps)(
       ownerIdBytes,
       timestampToTimestampBytes(firstInArray(messages).timestamp),
     );
-    if (!usageResult.ok) return usageResult;
-
-    let { firstTimestamp, lastTimestamp } = usageResult.value;
+    if (!usage.ok) return usage;
+
+    let { firstTimestamp, lastTimestamp } = usage.value;
+
+    for (const { timestamp, change } of messages) {
+      const timestampBytes = timestampToTimestampBytes(timestamp);
+      const idBytes = idToIdBytes(change.id);
+      const columns = dbChangeToColumns(change, timestampToDateIso(timestamp));
+
+      for (const [column, value] of columns) {
+        const updateAppTable = deps.sqlite.exec(sql.prepared`
+          with
+            existingTimestamp as (
+              select 1
+              from evolu_history
+              where
+                "ownerId" = ${ownerIdBytes}
+                and "table" = ${change.table}
+                and "id" = ${idBytes}
+                and "column" = ${column}
+                and "timestamp" >= ${timestampBytes}
+              limit 1
+            )
+          insert into ${sql.identifier(change.table)}
+            ("ownerId", "id", ${sql.identifier(column)})
+          select ${ownerId}, ${change.id}, ${value}
+          where not exists (select 1 from existingTimestamp)
+          on conflict ("ownerId", "id") do update
+            set ${sql.identifier(column)} = ${value}
+            where not exists (select 1 from existingTimestamp);
+        `);
 
-    for (const message of messages) {
-      const date = timestampToDateIso(message.timestamp);
-      const result1 = applyMessageToAppTable(deps)(ownerIdBytes, message, date);
-      if (!result1.ok) return result1;
+        if (!updateAppTable.ok) return updateAppTable;
+
+        const insertHistory = deps.sqlite.exec(sql.prepared`
+          insert into evolu_history
+            ("ownerId", "table", "id", "column", "value", "timestamp")
+          values
+            (
+              ${ownerIdBytes},
+              ${change.table},
+              ${idBytes},
+              ${column},
+              ${value},
+              ${timestampBytes}
+            )
+          on conflict do nothing;
+        `);
 
-      const timestamp = timestampToTimestampBytes(message.timestamp);
+        if (!insertHistory.ok) return insertHistory;
+      }
 
       let strategy;
       [strategy, firstTimestamp, lastTimestamp] = getTimestampInsertStrategy(
-        timestamp,
+        timestampBytes,
         firstTimestamp,
         lastTimestamp,
       );
 
-      const result2 = applyMessageToTimestampAndHistoryTables(deps)(
+      const insertTimestamp = deps.storage.insertTimestamp(
         ownerIdBytes,
-        message,
+        timestampBytes,
         strategy,
-        date,
       );
-      if (!result2.ok) return result2;
+      if (!insertTimestamp.ok) return insertTimestamp;
     }
 
     /**
@@ -741,98 +781,6 @@ const applyMessages =
     return ok();
   };
 
-const applyMessageToAppTable =
-  (deps: SqliteDep) =>
-  (
-    ownerIdBytes: OwnerIdBytes,
-    message: CrdtMessage,
-    date: DateIso,
-  ): Result<void, SqliteError> => {
-    const ownerId = ownerIdBytesToOwnerId(ownerIdBytes);
-    const columns = dbChangeToColumns(message.change, date);
-
-    for (const [column, value] of columns) {
-      const result = deps.sqlite.exec(sql.prepared`
-        with
-          existingTimestamp as (
-            select 1
-            from evolu_history
-            where
-              "ownerId" = ${ownerIdBytes}
-              and "table" = ${message.change.table}
-              and "id" = ${idToIdBytes(message.change.id)}
-              and "column" = ${column}
-              and "timestamp" >= ${timestampToTimestampBytes(message.timestamp)}
-            limit 1
-          )
-        insert into ${sql.identifier(message.change.table)}
-          ("ownerId", "id", ${sql.identifier(column)}, updatedAt)
-        select ${ownerId}, ${message.change.id}, ${value}, ${date}
-        where not exists (select 1 from existingTimestamp)
-        on conflict ("ownerId", "id") do update
-          set
-            ${sql.identifier(column)} = ${value},
-            updatedAt = ${date}
-          where not exists (select 1 from existingTimestamp);
-      `);
-
-      if (!result.ok) return result;
-    }
-
-    return ok();
-  };
-
-export const applyMessageToTimestampAndHistoryTables =
-  (deps: ClientStorageDep & SqliteDep) =>
-  (
-    ownerId: OwnerIdBytes,
-    message: CrdtMessage,
-    strategy: StorageInsertTimestampStrategy,
-    date: DateIso,
-  ): Result<void, SqliteError> => {
-    const timestamp = timestampToTimestampBytes(message.timestamp);
-    const id = idToIdBytes(message.change.id);
-
-    const result = deps.storage.insertTimestamp(ownerId, timestamp, strategy);
-    if (!result.ok) return result;
-
-    const columns = dbChangeToColumns(message.change, date);
-
-    for (const [column, value] of columns) {
-      const result = deps.sqlite.exec(sql.prepared`
-        insert into evolu_history
-          ("ownerId", "table", "id", "column", "value", "timestamp")
-        values
-          (
-            ${ownerId},
-            ${message.change.table},
-            ${id},
-            ${column},
-            ${value},
-            ${timestamp}
-          )
-        on conflict do nothing;
-      `);
-      if (!result.ok) return result;
-    }
-
-    return ok();
-  };
-
-const dbChangeToColumns = (
-  change: DbChange,
-  date: DateIso,
-): Array<[string, SqliteValue | DateIso]> => {
-  const entries = [...objectToEntries(change.values)];
-  if (change.isInsert) {
-    entries.push(["createdAt", date]);
-  }
-  if (change.isDelete !== null) {
-    entries.push(["isDeleted", booleanToSqliteBoolean(change.isDelete)]);
-  }
-  return entries;
-};
-
 /**
  * TODO: Rework for the new owners API.
  *

package/src/local-first/Timestamp.ts

@@ -336,8 +336,21 @@ export const timestampBytesToTimestamp = (
   return { millis: Number(millis), counter, nodeId } as Timestamp;
 };
 
+/**
+ * An {@link Order} for {@link TimestampBytes}.
+ *
+ * This `Order` uses lexicographic byte order to compare serialized
+ * {@link TimestampBytes} produced by {@link timestampToTimestampBytes}. See
+ * {@link orderUint8Array} for the underlying implementation.
+ */
 export const orderTimestampBytes: Order<TimestampBytes> = orderUint8Array;
 
+/**
+ * Convert a {@link Timestamp} to an ISO 8601 {@link DateIso} string.
+ *
+ * The conversion uses the timestamp's `millis` (a {@link Millis} value) and
+ * `Date.prototype.toISOString()` to produce a `DateIso`.
+ */
 export const timestampToDateIso = (timestamp: Timestamp): DateIso =>
-  // `as DateIso` is safe because the timestamp is always valid
+  // `as DateIso` is safe because Timestamp guarantees a valid `millis`
   new Date(timestamp.millis).toISOString() as DateIso;