jsgar 3.8.3 → 4.0.1

package/dist/gar.umd.js

@@ -54,7 +54,8 @@
                 this.scaledHeartbeatTimeoutInterval *= this.timeoutScale;
             }
             this.unique_key_and_record_updates = uniqueKeyAndRecordUpdates;
-            this.version = 650707;
+            this.version = 650708;
+            this.uuid = GARClient._generateUUID();
 
             if (typeof window !== 'undefined' && window.location) {
                 this.application = window.location.href;
@@ -412,6 +413,15 @@
             }, subscriptionGroup);
         }
 
+        /**
+         * Register handler for JSONCompareExchangeResult message.
+         * @param {Function} handler - Callback with (message)
+         * @param {number} [subscriptionGroup=0] - The subscription group for callback
+         */
+        registerCompareExchangeResultHandler(handler, subscriptionGroup = 0) {
+            this.registerHandler('JSONCompareExchangeResult', handler, subscriptionGroup);
+        }
+
         /**
          * Register handler for BatchUpdate message.
          * If a batch handler is registered it is expected to process all the updates in the batch.
@@ -508,6 +518,7 @@
                     version: this.version,
                     heartbeat_timeout_interval: Math.floor(this.scaledHeartbeatTimeoutInterval),
                     unique_key_and_record_updates: this.unique_key_and_record_updates,
+                    uuid: this.uuid,
                     user: this.user,
                     working_namespace: this.working_namespace
                 }
@@ -758,6 +769,8 @@
                 // New Introduction: do not reset the first-heartbeat promise to avoid racing
                 // with consumers already awaiting it. The existing promise will resolve on
                 // the first Heartbeat observed during the grace period above.
+            } else if (msgType === 'JSONCompareExchangeResult') {
+                subscriptionGroup = this.activeSubscriptionGroup;
             } else if (msgType === 'JSONRecordUpdate') {
                 subscriptionGroup = this.activeSubscriptionGroup;
                 const recordId = message.value.record_id;
@@ -903,6 +916,7 @@
          * @param {number} [snapshotSizeLimit=0] - Limit snapshot size
          * @param {number} [nagleInterval=0] - Nagle interval in milliseconds
          * @param {number} [limit=0] - Limits records in initial snapshot (0 = all)
+         * @param {string|Array<string>|null} [referencingClassList=null] - Referencing class name(s); if provided, include referencing keys and records per proto.gar subscribe.referencing_class_list
          */
         subscribe(
             name,
@@ -924,7 +938,8 @@
             subscriptionSet = null,
             snapshotSizeLimit = 0,
             nagleInterval = 0,
-            limit = 0
+            limit = 0,
+            referencingClassList = null
         ) {
             // Validate mutually exclusive parameters
             if (keyName && (keyFilter || excludeKeyFilter)) {
@@ -948,6 +963,14 @@
                 classList = className;
             }
 
+            // Normalize referencingClassList to an array
+            let referencingClasses = null;
+            if (typeof referencingClassList === 'string') {
+                referencingClasses = referencingClassList.split(/\s+/).filter(Boolean);
+            } else if (Array.isArray(referencingClassList)) {
+                referencingClasses = referencingClassList;
+            }
+
             let singleClass = Array.isArray(classList) && classList.length === 1 ? classList[0] : null;
 
             // Convert keyName to array
@@ -1014,6 +1037,9 @@
             if (classList) {
                 valueDict.class_list = classList;
             }
+            if (referencingClasses && referencingClasses.length > 0) {
+                valueDict.referencing_class_list = referencingClasses;
+            }
             if (keyFilter) {
                 valueDict.key_filter = keyFilter;
             }
@@ -1222,6 +1248,34 @@
             this.publishRecordWithIds(keyId, topicId, value);
         }
 
+        /**
+         * Send a compare-exchange using explicit key and topic IDs.
+         * @param {number} keyId - Key ID
+         * @param {number} topicId - Topic ID
+         * @param {any} test - Expected current value (null = expect missing/empty)
+         * @param {any} value - New value to set on match
+         */
+        compareExchangeRecordWithIds(keyId, topicId, test, value) {
+            this.sendMessage({
+                message_type: 'JSONCompareExchange',
+                value: { record_id: { key_id: keyId, topic_id: topicId }, test, value }
+            });
+        }
+
+        /**
+         * Send a compare-exchange using names, converting to local IDs.
+         * @param {string} keyName - Key name
+         * @param {string} topicName - Topic name
+         * @param {any} test - Expected current value (null = expect missing/empty)
+         * @param {any} value - New value to set on match
+         * @param {string|null} [className=null] - Class name
+         */
+        compareExchangeRecord(keyName, topicName, test, value, className = null) {
+            const keyId = this.getAndPossiblyIntroduceKeyId(keyName, className);
+            const topicId = this.getAndPossiblyIntroduceTopicId(topicName);
+            this.compareExchangeRecordWithIds(keyId, topicId, test, value);
+        }
+
         /**
          * Query GAR deployment routing to find servers with matching publications.
          * Mirrors the Python client's route_query implementation.
@@ -1401,6 +1455,18 @@
                 }, Math.max(0, Math.floor(timeout * 1000)));
             });
         }
+
+        static _generateUUID() {
+            const bytes = new Uint8Array(16);
+            if (typeof globalThis.crypto !== 'undefined' && globalThis.crypto.getRandomValues)
+                globalThis.crypto.getRandomValues(bytes);
+            else
+                require('crypto').randomFillSync(bytes);
+            bytes[6] = (bytes[6] & 0x0f) | 0x40; // version 4
+            bytes[8] = (bytes[8] & 0x3f) | 0x80; // variant RFC 4122
+            const view = new DataView(bytes.buffer);
+            return { low: Number(view.getBigUint64(0, true)), high: Number(view.getBigUint64(8, true)) };
+        }
     }
 
     return GARClient;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsgar",
-  "version": "3.8.3",
+  "version": "4.0.1",
   "description": "A Javascript client for the GAR protocol",
   "type": "module",
   "main": "dist/gar.umd.js",