@synclib-io/sync 0.2.0 → 0.2.1

package/dist/index.d.mts

@@ -552,6 +552,15 @@ declare class SyncClient {
     private serverHashColumns?;
     private isInitialized;
     private hasConnectedOnce;
+    /**
+     * Per-install identifier minted on first DB open and persisted in
+     * `_synclib_metadata`. Stable for the life of the SQLite/IndexedDB file.
+     * Sent on every join/push so the server can track per-device ack state
+     * and reliably trim the local outbound queue on reconnect (analog of the
+     * Dart `synclib_sync` implementation).
+     */
+    private deviceId;
+    getDeviceId(): string | null;
     private pendingAcks;
     private pendingChangeInfo;
     private remoteChangeListeners;
@@ -584,6 +593,16 @@ declare class SyncClient {
     private get pullChannels();
     /** Get all sync table names from channels config. */
     private get allSyncTables();
+    /**
+     * Load the per-install `device_id` from `_synclib_metadata`, or mint and
+     * persist one if it doesn't exist yet. UUID v4 via `crypto.randomUUID()`
+     * (Node 14.17+, modern browsers), falling back to a manual constructor
+     * if the host lacks it.
+     *
+     * `_synclib_metadata` is created here (idempotent CREATE TABLE IF NOT
+     * EXISTS) so this can be called before the row_hash migration runs.
+     */
+    private ensureDeviceId;
     /**
      * One-time migration: switch to server-authoritative row_hash.
      * Sets all local row_hash values to '' (sentinel) so merkle comparison
@@ -706,6 +725,24 @@ declare class SyncClient {
      * Extract server-driven hash_columns from a channel join response.
      */
     private extractServerHashColumns;
+    /**
+     * Reconcile the local outbound queue (`_sync_changes`) with the server's
+     * per-device high-water mark reported on the channel join response. If
+     * the server tells us "I've already applied your local_seqnum up to N for
+     * this device on this channel," DELETE everything at or below N from the
+     * queue — those writes are guaranteed-committed, even if their acks never
+     * reached us (network drop, app crash, server restart between apply and
+     * ack send). Idempotent and safe on every join.
+     *
+     * CRITICAL: scope by table_name. Local seqnums in `_sync_changes` are
+     * AUTOINCREMENT-global across the file (one counter for ALL channels),
+     * while the server's high-water mark is per-(device, channel). An
+     * unscoped `markSynced(N)` would `DELETE WHERE seqnum <= N` and could
+     * sweep up unpushed writes for OTHER channels whose seqnums happen to
+     * fall below N. Filtering by the channel's table set keeps the delete
+     * correct in the multi-channel case.
+     */
+    private trimQueueFromJoinResponse;
     /**
      * Send hello message to server
      */

package/dist/index.d.ts

@@ -552,6 +552,15 @@ declare class SyncClient {
     private serverHashColumns?;
     private isInitialized;
     private hasConnectedOnce;
+    /**
+     * Per-install identifier minted on first DB open and persisted in
+     * `_synclib_metadata`. Stable for the life of the SQLite/IndexedDB file.
+     * Sent on every join/push so the server can track per-device ack state
+     * and reliably trim the local outbound queue on reconnect (analog of the
+     * Dart `synclib_sync` implementation).
+     */
+    private deviceId;
+    getDeviceId(): string | null;
     private pendingAcks;
     private pendingChangeInfo;
     private remoteChangeListeners;
@@ -584,6 +593,16 @@ declare class SyncClient {
     private get pullChannels();
     /** Get all sync table names from channels config. */
     private get allSyncTables();
+    /**
+     * Load the per-install `device_id` from `_synclib_metadata`, or mint and
+     * persist one if it doesn't exist yet. UUID v4 via `crypto.randomUUID()`
+     * (Node 14.17+, modern browsers), falling back to a manual constructor
+     * if the host lacks it.
+     *
+     * `_synclib_metadata` is created here (idempotent CREATE TABLE IF NOT
+     * EXISTS) so this can be called before the row_hash migration runs.
+     */
+    private ensureDeviceId;
     /**
      * One-time migration: switch to server-authoritative row_hash.
      * Sets all local row_hash values to '' (sentinel) so merkle comparison
@@ -706,6 +725,24 @@ declare class SyncClient {
      * Extract server-driven hash_columns from a channel join response.
      */
     private extractServerHashColumns;
+    /**
+     * Reconcile the local outbound queue (`_sync_changes`) with the server's
+     * per-device high-water mark reported on the channel join response. If
+     * the server tells us "I've already applied your local_seqnum up to N for
+     * this device on this channel," DELETE everything at or below N from the
+     * queue — those writes are guaranteed-committed, even if their acks never
+     * reached us (network drop, app crash, server restart between apply and
+     * ack send). Idempotent and safe on every join.
+     *
+     * CRITICAL: scope by table_name. Local seqnums in `_sync_changes` are
+     * AUTOINCREMENT-global across the file (one counter for ALL channels),
+     * while the server's high-water mark is per-(device, channel). An
+     * unscoped `markSynced(N)` would `DELETE WHERE seqnum <= N` and could
+     * sweep up unpushed writes for OTHER channels whose seqnums happen to
+     * fall below N. Filtering by the channel's table set keeps the delete
+     * correct in the multi-channel case.
+     */
+    private trimQueueFromJoinResponse;
     /**
      * Send hello message to server
      */

package/dist/index.js

@@ -922,6 +922,14 @@ var SyncClient = class {
   constructor(config) {
     this.isInitialized = false;
     this.hasConnectedOnce = false;
+    /**
+     * Per-install identifier minted on first DB open and persisted in
+     * `_synclib_metadata`. Stable for the life of the SQLite/IndexedDB file.
+     * Sent on every join/push so the server can track per-device ack state
+     * and reliably trim the local outbound queue on reconnect (analog of the
+     * Dart `synclib_sync` implementation).
+     */
+    this.deviceId = null;
     this.pendingAcks = /* @__PURE__ */ new Set();
     // Track which table/rowId corresponds to each pending change seqnum
     this.pendingChangeInfo = /* @__PURE__ */ new Map();
@@ -961,6 +969,9 @@ var SyncClient = class {
     this.ws.onMessage(this.enqueueMessage.bind(this));
     this.ws.onStateChange(this.handleStateChange.bind(this));
   }
+  getDeviceId() {
+    return this.deviceId;
+  }
   /** Get channels that push (push or bidirectional role). */
   get pushChannels() {
     return this.config.channels.filter(
@@ -983,6 +994,69 @@ var SyncClient = class {
     }
     return Array.from(tables);
   }
+  /**
+   * Load the per-install `device_id` from `_synclib_metadata`, or mint and
+   * persist one if it doesn't exist yet. UUID v4 via `crypto.randomUUID()`
+   * (Node 14.17+, modern browsers), falling back to a manual constructor
+   * if the host lacks it.
+   *
+   * `_synclib_metadata` is created here (idempotent CREATE TABLE IF NOT
+   * EXISTS) so this can be called before the row_hash migration runs.
+   */
+  ensureDeviceId() {
+    try {
+      this.db.exec(`
+        CREATE TABLE IF NOT EXISTS _synclib_metadata (
+          key TEXT PRIMARY KEY,
+          value TEXT NOT NULL
+        )
+      `);
+      const results = this.db.read(
+        `SELECT value FROM _synclib_metadata WHERE key = 'device_id'`
+      );
+      if (results.length > 0 && results[0].value) {
+        this.deviceId = String(results[0].value);
+        console.log(`[SyncClient] Loaded device_id: ${this.deviceId}`);
+        return;
+      }
+      const cryptoObj = globalThis.crypto;
+      let uuid;
+      if (cryptoObj?.randomUUID) {
+        uuid = cryptoObj.randomUUID();
+      } else if (cryptoObj?.getRandomValues) {
+        const bytes = new Uint8Array(16);
+        cryptoObj.getRandomValues(bytes);
+        bytes[6] = bytes[6] & 15 | 64;
+        bytes[8] = bytes[8] & 63 | 128;
+        const hex = (b) => b.toString(16).padStart(2, "0");
+        uuid = `${hex(bytes[0])}${hex(bytes[1])}${hex(bytes[2])}${hex(bytes[3])}-${hex(bytes[4])}${hex(bytes[5])}-${hex(bytes[6])}${hex(bytes[7])}-${hex(bytes[8])}${hex(bytes[9])}-${hex(bytes[10])}${hex(bytes[11])}${hex(bytes[12])}${hex(bytes[13])}${hex(bytes[14])}${hex(bytes[15])}`;
+      } else {
+        const r = () => Math.floor(Math.random() * 65535).toString(16).padStart(4, "0");
+        uuid = `${r()}${r()}-${r()}-4${r().slice(1)}-${((Math.random() * 4 | 0) + 8).toString(16)}${r().slice(1)}-${r()}${r()}${r()}`;
+      }
+      const escaped = uuid.replace(/'/g, "''");
+      this.db.exec(
+        `INSERT OR IGNORE INTO _synclib_metadata (key, value) VALUES ('device_id', '${escaped}')`
+      );
+      this.deviceId = uuid;
+      try {
+        const reread = this.db.read(
+          `SELECT value FROM _synclib_metadata WHERE key = 'device_id'`
+        );
+        if (reread.length > 0 && reread[0].value) {
+          this.deviceId = String(reread[0].value);
+        }
+      } catch (e) {
+        console.warn(
+          "[SyncClient] device_id re-read failed; keeping tentative mint:",
+          e
+        );
+      }
+      console.log(`[SyncClient] Minted device_id: ${this.deviceId}`);
+    } catch (e) {
+      console.warn("[SyncClient] Failed to ensure device_id:", e);
+    }
+  }
   /**
    * One-time migration: switch to server-authoritative row_hash.
    * Sets all local row_hash values to '' (sentinel) so merkle comparison
@@ -1027,6 +1101,7 @@ var SyncClient = class {
     }
     console.log("Initializing sync client");
     this.migrateToServerAuthoritativeRowHash();
+    this.ensureDeviceId();
     this.isInitialized = true;
   }
   /**
@@ -1073,9 +1148,11 @@ var SyncClient = class {
       console.log(`Joining channel: ${topic}`);
       const response = await this.ws.joinChannel(topic, {
         client_id: this.config.clientId,
+        ...this.deviceId ? { device_id: this.deviceId } : {},
         ...channel.params
       });
       this.extractServerHashColumns(response);
+      this.trimQueueFromJoinResponse(response, topic);
     }
     console.log("All channels joined successfully");
     this.hasConnectedOnce = true;
@@ -1093,9 +1170,11 @@ var SyncClient = class {
     console.log(`Joining additional channel: ${topic}`);
     const response = await this.ws.joinChannel(topic, {
       client_id: this.config.clientId,
+      ...this.deviceId ? { device_id: this.deviceId } : {},
       ...channel.params
     });
     this.extractServerHashColumns(response);
+    this.trimQueueFromJoinResponse(response, topic);
     console.log(`Successfully joined channel: ${topic}`);
   }
   /**
@@ -1176,6 +1255,7 @@ var SyncClient = class {
       const tableSeqnums = await this.getPerTableSeqnums(tablesToSync);
       const payload = {
         client_id: this.config.clientId,
+        ...this.deviceId ? { device_id: this.deviceId } : {},
         schema_version: schemaVersion,
         table_seqnums: tableSeqnums,
         tables: tablesToSync
@@ -1353,6 +1433,54 @@ var SyncClient = class {
       console.log(`Server hash_columns: ${this.serverHashColumns.join(", ")}`);
     }
   }
+  /**
+   * Reconcile the local outbound queue (`_sync_changes`) with the server's
+   * per-device high-water mark reported on the channel join response. If
+   * the server tells us "I've already applied your local_seqnum up to N for
+   * this device on this channel," DELETE everything at or below N from the
+   * queue — those writes are guaranteed-committed, even if their acks never
+   * reached us (network drop, app crash, server restart between apply and
+   * ack send). Idempotent and safe on every join.
+   *
+   * CRITICAL: scope by table_name. Local seqnums in `_sync_changes` are
+   * AUTOINCREMENT-global across the file (one counter for ALL channels),
+   * while the server's high-water mark is per-(device, channel). An
+   * unscoped `markSynced(N)` would `DELETE WHERE seqnum <= N` and could
+   * sweep up unpushed writes for OTHER channels whose seqnums happen to
+   * fall below N. Filtering by the channel's table set keeps the delete
+   * correct in the multi-channel case.
+   */
+  trimQueueFromJoinResponse(response, channelTopic) {
+    const lastApplied = response?.last_applied_local_seqnum;
+    if (typeof lastApplied !== "number" || lastApplied <= 0) {
+      return;
+    }
+    const channel = this.config.channels.find((c) => c.topic === channelTopic);
+    if (!channel) {
+      console.warn(
+        `[SyncClient] No SyncChannel found for topic ${channelTopic}; skipping trim`
+      );
+      return;
+    }
+    const tables = (channel.tables || []).map((t) => t.name);
+    if (tables.length === 0) {
+      return;
+    }
+    try {
+      const escapedTables = tables.map((t) => `'${t.replace(/'/g, "''")}'`).join(",");
+      this.db.exec(
+        `DELETE FROM _sync_changes WHERE seqnum <= ${lastApplied} AND table_name IN (${escapedTables})`
+      );
+      console.log(
+        `[SyncClient] Reconciled outbound queue on ${channelTopic}: trimmed seqnum <= ${lastApplied} scoped to ${tables.length} table(s)`
+      );
+    } catch (e) {
+      console.warn(
+        `[SyncClient] Failed to trim queue at seqnum ${lastApplied} on ${channelTopic}:`,
+        e
+      );
+    }
+  }
   /**
    * Send hello message to server
    */

package/dist/index.mjs

@@ -889,6 +889,14 @@ var SyncClient = class {
   constructor(config) {
     this.isInitialized = false;
     this.hasConnectedOnce = false;
+    /**
+     * Per-install identifier minted on first DB open and persisted in
+     * `_synclib_metadata`. Stable for the life of the SQLite/IndexedDB file.
+     * Sent on every join/push so the server can track per-device ack state
+     * and reliably trim the local outbound queue on reconnect (analog of the
+     * Dart `synclib_sync` implementation).
+     */
+    this.deviceId = null;
     this.pendingAcks = /* @__PURE__ */ new Set();
     // Track which table/rowId corresponds to each pending change seqnum
     this.pendingChangeInfo = /* @__PURE__ */ new Map();
@@ -928,6 +936,9 @@ var SyncClient = class {
     this.ws.onMessage(this.enqueueMessage.bind(this));
     this.ws.onStateChange(this.handleStateChange.bind(this));
   }
+  getDeviceId() {
+    return this.deviceId;
+  }
   /** Get channels that push (push or bidirectional role). */
   get pushChannels() {
     return this.config.channels.filter(
@@ -950,6 +961,69 @@ var SyncClient = class {
     }
     return Array.from(tables);
   }
+  /**
+   * Load the per-install `device_id` from `_synclib_metadata`, or mint and
+   * persist one if it doesn't exist yet. UUID v4 via `crypto.randomUUID()`
+   * (Node 14.17+, modern browsers), falling back to a manual constructor
+   * if the host lacks it.
+   *
+   * `_synclib_metadata` is created here (idempotent CREATE TABLE IF NOT
+   * EXISTS) so this can be called before the row_hash migration runs.
+   */
+  ensureDeviceId() {
+    try {
+      this.db.exec(`
+        CREATE TABLE IF NOT EXISTS _synclib_metadata (
+          key TEXT PRIMARY KEY,
+          value TEXT NOT NULL
+        )
+      `);
+      const results = this.db.read(
+        `SELECT value FROM _synclib_metadata WHERE key = 'device_id'`
+      );
+      if (results.length > 0 && results[0].value) {
+        this.deviceId = String(results[0].value);
+        console.log(`[SyncClient] Loaded device_id: ${this.deviceId}`);
+        return;
+      }
+      const cryptoObj = globalThis.crypto;
+      let uuid;
+      if (cryptoObj?.randomUUID) {
+        uuid = cryptoObj.randomUUID();
+      } else if (cryptoObj?.getRandomValues) {
+        const bytes = new Uint8Array(16);
+        cryptoObj.getRandomValues(bytes);
+        bytes[6] = bytes[6] & 15 | 64;
+        bytes[8] = bytes[8] & 63 | 128;
+        const hex = (b) => b.toString(16).padStart(2, "0");
+        uuid = `${hex(bytes[0])}${hex(bytes[1])}${hex(bytes[2])}${hex(bytes[3])}-${hex(bytes[4])}${hex(bytes[5])}-${hex(bytes[6])}${hex(bytes[7])}-${hex(bytes[8])}${hex(bytes[9])}-${hex(bytes[10])}${hex(bytes[11])}${hex(bytes[12])}${hex(bytes[13])}${hex(bytes[14])}${hex(bytes[15])}`;
+      } else {
+        const r = () => Math.floor(Math.random() * 65535).toString(16).padStart(4, "0");
+        uuid = `${r()}${r()}-${r()}-4${r().slice(1)}-${((Math.random() * 4 | 0) + 8).toString(16)}${r().slice(1)}-${r()}${r()}${r()}`;
+      }
+      const escaped = uuid.replace(/'/g, "''");
+      this.db.exec(
+        `INSERT OR IGNORE INTO _synclib_metadata (key, value) VALUES ('device_id', '${escaped}')`
+      );
+      this.deviceId = uuid;
+      try {
+        const reread = this.db.read(
+          `SELECT value FROM _synclib_metadata WHERE key = 'device_id'`
+        );
+        if (reread.length > 0 && reread[0].value) {
+          this.deviceId = String(reread[0].value);
+        }
+      } catch (e) {
+        console.warn(
+          "[SyncClient] device_id re-read failed; keeping tentative mint:",
+          e
+        );
+      }
+      console.log(`[SyncClient] Minted device_id: ${this.deviceId}`);
+    } catch (e) {
+      console.warn("[SyncClient] Failed to ensure device_id:", e);
+    }
+  }
   /**
    * One-time migration: switch to server-authoritative row_hash.
    * Sets all local row_hash values to '' (sentinel) so merkle comparison
@@ -994,6 +1068,7 @@ var SyncClient = class {
     }
     console.log("Initializing sync client");
     this.migrateToServerAuthoritativeRowHash();
+    this.ensureDeviceId();
     this.isInitialized = true;
   }
   /**
@@ -1040,9 +1115,11 @@ var SyncClient = class {
       console.log(`Joining channel: ${topic}`);
       const response = await this.ws.joinChannel(topic, {
         client_id: this.config.clientId,
+        ...this.deviceId ? { device_id: this.deviceId } : {},
         ...channel.params
       });
       this.extractServerHashColumns(response);
+      this.trimQueueFromJoinResponse(response, topic);
     }
     console.log("All channels joined successfully");
     this.hasConnectedOnce = true;
@@ -1060,9 +1137,11 @@ var SyncClient = class {
     console.log(`Joining additional channel: ${topic}`);
     const response = await this.ws.joinChannel(topic, {
       client_id: this.config.clientId,
+      ...this.deviceId ? { device_id: this.deviceId } : {},
       ...channel.params
     });
     this.extractServerHashColumns(response);
+    this.trimQueueFromJoinResponse(response, topic);
     console.log(`Successfully joined channel: ${topic}`);
   }
   /**
@@ -1143,6 +1222,7 @@ var SyncClient = class {
       const tableSeqnums = await this.getPerTableSeqnums(tablesToSync);
       const payload = {
         client_id: this.config.clientId,
+        ...this.deviceId ? { device_id: this.deviceId } : {},
         schema_version: schemaVersion,
         table_seqnums: tableSeqnums,
         tables: tablesToSync
@@ -1320,6 +1400,54 @@ var SyncClient = class {
       console.log(`Server hash_columns: ${this.serverHashColumns.join(", ")}`);
     }
   }
+  /**
+   * Reconcile the local outbound queue (`_sync_changes`) with the server's
+   * per-device high-water mark reported on the channel join response. If
+   * the server tells us "I've already applied your local_seqnum up to N for
+   * this device on this channel," DELETE everything at or below N from the
+   * queue — those writes are guaranteed-committed, even if their acks never
+   * reached us (network drop, app crash, server restart between apply and
+   * ack send). Idempotent and safe on every join.
+   *
+   * CRITICAL: scope by table_name. Local seqnums in `_sync_changes` are
+   * AUTOINCREMENT-global across the file (one counter for ALL channels),
+   * while the server's high-water mark is per-(device, channel). An
+   * unscoped `markSynced(N)` would `DELETE WHERE seqnum <= N` and could
+   * sweep up unpushed writes for OTHER channels whose seqnums happen to
+   * fall below N. Filtering by the channel's table set keeps the delete
+   * correct in the multi-channel case.
+   */
+  trimQueueFromJoinResponse(response, channelTopic) {
+    const lastApplied = response?.last_applied_local_seqnum;
+    if (typeof lastApplied !== "number" || lastApplied <= 0) {
+      return;
+    }
+    const channel = this.config.channels.find((c) => c.topic === channelTopic);
+    if (!channel) {
+      console.warn(
+        `[SyncClient] No SyncChannel found for topic ${channelTopic}; skipping trim`
+      );
+      return;
+    }
+    const tables = (channel.tables || []).map((t) => t.name);
+    if (tables.length === 0) {
+      return;
+    }
+    try {
+      const escapedTables = tables.map((t) => `'${t.replace(/'/g, "''")}'`).join(",");
+      this.db.exec(
+        `DELETE FROM _sync_changes WHERE seqnum <= ${lastApplied} AND table_name IN (${escapedTables})`
+      );
+      console.log(
+        `[SyncClient] Reconciled outbound queue on ${channelTopic}: trimmed seqnum <= ${lastApplied} scoped to ${tables.length} table(s)`
+      );
+    } catch (e) {
+      console.warn(
+        `[SyncClient] Failed to trim queue at seqnum ${lastApplied} on ${channelTopic}:`,
+        e
+      );
+    }
+  }
   /**
    * Send hello message to server
    */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synclib-io/sync",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "TypeScript/JavaScript sync client for coordinating database changes with Elixir Phoenix server",
   "publishConfig": {
     "access": "public"