jsgar 4.13.0 → 4.13.3

package/dist/gar.umd.js

@@ -852,6 +852,31 @@
          */
         sendMessage(message) {
             this.messageQueue.push(message);
+            // Drain synchronously when possible: background tabs throttle timers — the polling
+            // drain loop (and any setInterval sender) can stretch from 100ms to minutes — but
+            // synchronous sends from an event or enqueue are never throttled.
+            this._flushQueue();
+        }
+
+        /**
+         * Synchronously send everything sendable. Safe alongside the polling loop (same JS
+         * thread); leaves the null shutdown sentinel for the loop's exit handling.
+         */
+        _flushQueue() {
+            while (this.connected && this.messageQueue.length > 0 && this._isSocketOpen()) {
+                if (this.messageQueue[0] === null) return;
+                const message = this.messageQueue.shift();
+                try {
+                    this.websocket.send(JSON.stringify(message));
+                    if (this.logEveryMessage) {
+                        this.log('INFO', `Sent: ${JSON.stringify(message)}`);
+                    }
+                } catch (e) {
+                    this.log('WARNING', `Error sending message: ${e.message}`);
+                    this.halt();
+                    return;
+                }
+            }
         }
 
         /**
@@ -979,6 +1004,13 @@
                 this.invalidatedKeyIds.add(message.value.client_introduced_key_id);
             } else if (msgType === 'Heartbeat') {
                 this.lastHeartbeatTime = Date.now() / 1000;
+                // Echo our own heartbeat on the server's cadence. A hidden tab's throttled timers
+                // can silence the periodic sender far past the server's timeout while this
+                // (unthrottled) receive path keeps delivering — the server then rightly declares
+                // us dead. Event-driven liveness: receive -> reply, flushed synchronously above.
+                if (this.running) {
+                    this.sendMessage({ message_type: 'Heartbeat', value: { u_milliseconds: Date.now() } });
+                }
                 if (this._initialGracePeriod) {
                     // Resolve first-heartbeat waiters and end the initial grace window
                     if (this._firstHeartbeatResolve) {
@@ -1147,7 +1179,9 @@
          * @param {Object} opts - Named subscription options (fields below).
          * @param {string} opts.name - Subscription name
          * @param {string} [opts.subscriptionMode='Streaming'] - Subscription mode
-         * @param {string|Array<string>|null} [keyName=null] - Key name(s)
+         * @param {string|Array<string>|Array<number>|null} [keyName=null] - Key name(s), matched
+         *     exactly via a synthesized key_filter alternation (keys are NOT created by
+         *     subscribing); an array of integers passes through as the wire key_id_list
          * @param {string|Array<string>|null} [topicName=null] - Topic name(s)
          * @param {string|Array<string>|null} [className=null] - Class name(s)
          * @param {string|null} [keyFilter=null] - Key filter regex (cannot use with keyName)
@@ -1226,16 +1260,24 @@
                 referencingClasses = referencingClassList;
             }
 
-            let singleClass = Array.isArray(classList) && classList.length === 1 ? classList[0] : null;
-
-            // Convert keyName to array
+            // Convert keyName to array. Subscribing must NOT create keys: names are no longer
+            // introduced to build a key_id_list (the old behavior materialized every named key on
+            // the server). Names become an exact-match alternation key_filter instead — the server
+            // recognizes the literal-alternation shape and builds a trie, skipping the full
+            // regex->DFA compilation. An array of integers passes through as key_id_list verbatim
+            // (the caller already holds real key ids).
             let keyNames = [];
             if (typeof keyName === 'string') {
                 keyNames = [keyName];
             } else if (Array.isArray(keyName)) {
                 keyNames = keyName;
             }
-            const keyIdList = keyNames.map(x => this.getAndPossiblyIntroduceKeyId(x, singleClass));
+            let keyIdList = [];
+            if (keyNames.length > 0 && keyNames.every(Number.isInteger)) {
+                keyIdList = keyNames;
+            } else if (keyNames.length > 0) {
+                keyFilter = keyNames.map(GARClient.escapeRegex).join('|');
+            }
 
             // Convert topicName to array
             let topicNames = [];
@@ -1817,6 +1859,16 @@
             });
         }
 
+        /**
+         * Escape TRS-regex metacharacters so `name` matches literally (TRS regexes match the
+         * whole string, so an escaped name is an exact-match alternative in a key_filter).
+         * @param {string} name
+         * @returns {string}
+         */
+        static escapeRegex(name) {
+            return String(name).replace(/[\\.^$|?*+()[\]{}]/g, '\\$&');
+        }
+
         static _generateUUID() {
             const bytes = new Uint8Array(16);
             if (typeof globalThis.crypto !== 'undefined' && globalThis.crypto.getRandomValues)

package/gar.js

@@ -845,6 +845,31 @@ class GARClient {
      */
     sendMessage(message) {
         this.messageQueue.push(message);
+        // Drain synchronously when possible: background tabs throttle timers — the polling
+        // drain loop (and any setInterval sender) can stretch from 100ms to minutes — but
+        // synchronous sends from an event or enqueue are never throttled.
+        this._flushQueue();
+    }
+
+    /**
+     * Synchronously send everything sendable. Safe alongside the polling loop (same JS
+     * thread); leaves the null shutdown sentinel for the loop's exit handling.
+     */
+    _flushQueue() {
+        while (this.connected && this.messageQueue.length > 0 && this._isSocketOpen()) {
+            if (this.messageQueue[0] === null) return;
+            const message = this.messageQueue.shift();
+            try {
+                this.websocket.send(JSON.stringify(message));
+                if (this.logEveryMessage) {
+                    this.log('INFO', `Sent: ${JSON.stringify(message)}`);
+                }
+            } catch (e) {
+                this.log('WARNING', `Error sending message: ${e.message}`);
+                this.halt();
+                return;
+            }
+        }
     }
 
     /**
@@ -972,6 +997,13 @@ class GARClient {
             this.invalidatedKeyIds.add(message.value.client_introduced_key_id);
         } else if (msgType === 'Heartbeat') {
             this.lastHeartbeatTime = Date.now() / 1000;
+            // Echo our own heartbeat on the server's cadence. A hidden tab's throttled timers
+            // can silence the periodic sender far past the server's timeout while this
+            // (unthrottled) receive path keeps delivering — the server then rightly declares
+            // us dead. Event-driven liveness: receive -> reply, flushed synchronously above.
+            if (this.running) {
+                this.sendMessage({ message_type: 'Heartbeat', value: { u_milliseconds: Date.now() } });
+            }
             if (this._initialGracePeriod) {
                 // Resolve first-heartbeat waiters and end the initial grace window
                 if (this._firstHeartbeatResolve) {
@@ -1140,7 +1172,9 @@ class GARClient {
      * @param {Object} opts - Named subscription options (fields below).
      * @param {string} opts.name - Subscription name
      * @param {string} [opts.subscriptionMode='Streaming'] - Subscription mode
-     * @param {string|Array<string>|null} [keyName=null] - Key name(s)
+     * @param {string|Array<string>|Array<number>|null} [keyName=null] - Key name(s), matched
+     *     exactly via a synthesized key_filter alternation (keys are NOT created by
+     *     subscribing); an array of integers passes through as the wire key_id_list
      * @param {string|Array<string>|null} [topicName=null] - Topic name(s)
      * @param {string|Array<string>|null} [className=null] - Class name(s)
      * @param {string|null} [keyFilter=null] - Key filter regex (cannot use with keyName)
@@ -1219,16 +1253,24 @@ class GARClient {
             referencingClasses = referencingClassList;
         }
 
-        let singleClass = Array.isArray(classList) && classList.length === 1 ? classList[0] : null;
-
-        // Convert keyName to array
+        // Convert keyName to array. Subscribing must NOT create keys: names are no longer
+        // introduced to build a key_id_list (the old behavior materialized every named key on
+        // the server). Names become an exact-match alternation key_filter instead — the server
+        // recognizes the literal-alternation shape and builds a trie, skipping the full
+        // regex->DFA compilation. An array of integers passes through as key_id_list verbatim
+        // (the caller already holds real key ids).
         let keyNames = [];
         if (typeof keyName === 'string') {
             keyNames = [keyName];
         } else if (Array.isArray(keyName)) {
             keyNames = keyName;
         }
-        const keyIdList = keyNames.map(x => this.getAndPossiblyIntroduceKeyId(x, singleClass));
+        let keyIdList = [];
+        if (keyNames.length > 0 && keyNames.every(Number.isInteger)) {
+            keyIdList = keyNames;
+        } else if (keyNames.length > 0) {
+            keyFilter = keyNames.map(GARClient.escapeRegex).join('|');
+        }
 
         // Convert topicName to array
         let topicNames = [];
@@ -1810,6 +1852,16 @@ class GARClient {
         });
     }
 
+    /**
+     * Escape TRS-regex metacharacters so `name` matches literally (TRS regexes match the
+     * whole string, so an escaped name is an exact-match alternative in a key_filter).
+     * @param {string} name
+     * @returns {string}
+     */
+    static escapeRegex(name) {
+        return String(name).replace(/[\\.^$|?*+()[\]{}]/g, '\\$&');
+    }
+
     static _generateUUID() {
         const bytes = new Uint8Array(16);
         if (typeof globalThis.crypto !== 'undefined' && globalThis.crypto.getRandomValues)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsgar",
-  "version": "4.13.0",
+  "version": "4.13.3",
   "description": "A Javascript client for the GAR protocol",
   "type": "module",
   "main": "dist/gar.umd.js",
@@ -36,6 +36,8 @@
     "@eslint/json": "^0.13.2",
     "@rollup/plugin-commonjs": "^24.0.0",
     "@rollup/plugin-node-resolve": "^15.0.0",
+    "@xterm/addon-fit": "^0.10.0",
+    "@xterm/xterm": "^5.5.0",
     "ag-grid-community": "^34.1.1",
     "ag-grid-enterprise": "^34.1.1",
     "eslint": "^9.39.4",