jsgar 4.8.0 → 4.9.1

package/dist/gar.umd.js

@@ -200,6 +200,7 @@
             this.websocket = null;
             this.messageQueue = [];
             this.connected = false;
+            this.connectedCallback = null;
             this.reconnectDelay = 5000; // Milliseconds
             this.user = user;
             this.working_namespace = working_namespace;
@@ -383,18 +384,18 @@
                     });
 
                     this.websocket = await connectionPromise;
-                    this.connected = true;
+                    this._setConnected(true);
                     this.log('INFO', `Connected to WebSocket server at ${this.wsEndpoint} using gar-protocol`);
 
                     this.websocket.onclose = () => {
                         this.log('WARNING', 'WebSocket connection closed.');
-                        this.connected = false;
+                        this._setConnected(false);
                         this.websocket = null;
                         this._reconnect();
                     };
                     this.websocket.onerror = (error) => {
                         this.log('ERROR', `WebSocket error: ${error.message || 'Unknown error'}`);
-                        this.connected = false;
+                        this._setConnected(false);
                         this.websocket = null;
                     };
 
@@ -402,7 +403,7 @@
                     this._receiveMessages();
 
                 } catch (e) {
-                    this.connected = false;
+                    this._setConnected(false);
                     this.websocket = null;
                     // 401 is a permanent auth rejection — retrying won't help
                     if (e.message && e.message.includes('401')) {
@@ -454,7 +455,7 @@
             }
             this.log('INFO', 'Done sending messages.');
             this.stop();
-            this.connected = false;
+            this._setConnected(false);
         }
 
         /**
@@ -467,6 +468,34 @@
             };
         }
 
+        /**
+         * Register a callback fired when the WS `connected` flag transitions.
+         * @param {Function} handler - Callback receiving the new boolean value
+         */
+        registerConnectedHandler(handler) {
+            this.connectedCallback = handler;
+        }
+
+        /**
+         * Clear the connected handler.
+         */
+        clearConnectedHandler() {
+            this.connectedCallback = null;
+        }
+
+        /**
+         * Internal setter that fires connectedCallback on state transitions.
+         * @param {boolean} value
+         */
+        _setConnected(value) {
+            if (this.connected === value) return;
+            this.connected = value;
+            if (this.connectedCallback) {
+                try { this.connectedCallback(value); }
+                catch (e) { this.log('ERROR', `connectedCallback threw: ${e.message}`); }
+            }
+        }
+
         /**
          * Register a callback handler for a specific message type.
          * @param {string} messageType - Type of message
@@ -802,7 +831,7 @@
          * Stop the client without sending pending messages.
          */
         halt() {
-            this.connected = false;
+            this._setConnected(false);
             this.stop();
         }
 
@@ -1072,9 +1101,18 @@
                 this.log('INFO', 'Received Logoff from server');
                 this.stop();
             } else if (msgType === 'Error') {
-                this.log('ERROR', `GAR ${message.value.message}`);
-                this.exitCode = 1;
-                this.stop();
+                // proto.gar's `error` struct carries `recoverable: bool`. Recoverable errors mean
+                // the server processed the failing message (e.g. a publish that violated some
+                // server-side check), logged it, and kept the connection alive. We dispatch the
+                // message to the user's error handler but don't tear down the client. Non-recoverable
+                // errors are followed by a server disconnect; we set exit_code + stop() so callers
+                // (CLI tools, the html_view UI) see the failure.
+                const recoverable = !!message.value.recoverable;
+                this.log(recoverable ? 'WARNING' : 'ERROR', `GAR ${message.value.message}`);
+                if (!recoverable) {
+                    this.exitCode = 1;
+                    this.stop();
+                }
             }
 
             this.checkHeartbeat();
@@ -1358,28 +1396,25 @@
         }
 
         /**
-         * Introduce a new key if not already known and return local key ID.
+         * Introduce a new key if not already known and return local key ID. className is required;
+         * a bare introduction with no class_list can't be routed by upstream proxies.
          * @param {string} name - Key name
-         * @param {string|Array<string>|null} [className=null] - Class name(s)
+         * @param {string|Array<string>} className - Class name(s)
          * @returns {number} Local key ID
          */
-        getAndPossiblyIntroduceKeyId(name, className = null) {
+        getAndPossiblyIntroduceKeyId(name, className) {
             const existingId = this.localKeyMap.get(name);
             if (existingId !== undefined && this.invalidatedKeyIds.has(existingId)) {
                 this.invalidatedKeyIds.delete(existingId);
                 this.localKeyMap.delete(name);
             }
             if (!this.localKeyMap.has(name)) {
+                if (!className) throw new Error(`getAndPossiblyIntroduceKeyId: className required to introduce key "${name}"`);
                 const keyId = this.localKeyCounter++;
                 this.localKeyMap.set(name, keyId);
                 const value = { key_id: keyId, name };
-                if (className) {
-                    if (typeof className === 'string') {
-                        value.class_list = className.split(/\s+/).filter(Boolean);
-                    } else if (Array.isArray(className)) {
-                        value.class_list = className;
-                    }
-                }
+                if (typeof className === 'string') value.class_list = className.split(/\s+/).filter(Boolean);
+                else if (Array.isArray(className)) value.class_list = className;
                 this.sendMessage({ message_type: 'KeyIntroduction', value });
             }
             return this.localKeyMap.get(name);
@@ -1421,11 +1456,24 @@
         /**
          * Delete a key by name if it exists in the localKeyMap. Safe to call multiple times.
          * @param {string} keyName - Key name
+         * @param {string|null} [className=null] - If set, removes the key from this class only via
+         *     a KeyIntroduction with deleted_class set; the key may still exist on the server in
+         *     other classes and the localKeyMap entry is preserved. If unset, sends DeleteKey to
+         *     remove the key entirely and forgets the local id so a future
+         *     getAndPossiblyIntroduceKeyId(keyName) re-introduces with a fresh id.
          */
-        deleteKey(keyName) {
+        deleteKey(keyName, className = null) {
             const keyId = this.localKeyMap.get(keyName);
-            if (keyId) {
+            if (keyId === undefined) return;
+            if (className) {
+                this.sendMessage({
+                    message_type: 'KeyIntroduction',
+                    value: { key_id: keyId, name: keyName, deleted_class: className },
+                });
+            } else {
                 this.publishDeleteKey(keyId);
+                // Forget the local id so future re-introduction allocates a new one.
+                this.localKeyMap.delete(keyName);
             }
         }
 
@@ -1469,6 +1517,10 @@
          * @param {any} value - JSON-serializable value
          */
         publishRecordWithIds(keyId, topicId, value) {
+            if (value === undefined) {
+                this.log('ERROR', `publishRecordWithIds(${keyId}, ${topicId}): refusing to publish undefined — JSON.stringify would drop the "value" field and the server would reject with "Missing record 'value' field"`);
+                return;
+            }
             const updateMsg = {
                 message_type: 'JSONRecordUpdate',
                 value: {
@@ -1487,6 +1539,10 @@
          * @param {string|null} [className=null] - Class name
          */
         publishRecord(keyName, topicName, value, className = null) {
+            if (value === undefined) {
+                this.log('ERROR', `publishRecord(${keyName}, ${topicName}): refusing to publish undefined — JSON.stringify would drop the "value" field and the server would reject with "Missing record 'value' field"`);
+                return;
+            }
             const keyId = this.getAndPossiblyIntroduceKeyId(keyName, className);
             const topicId = this.getAndPossiblyIntroduceTopicId(topicName);
             this.publishRecordWithIds(keyId, topicId, value);

package/gar.js

@@ -194,6 +194,7 @@ class GARClient {
         this.websocket = null;
         this.messageQueue = [];
         this.connected = false;
+        this.connectedCallback = null;
         this.reconnectDelay = 5000; // Milliseconds
         this.user = user;
         this.working_namespace = working_namespace;
@@ -377,18 +378,18 @@ class GARClient {
                 });
 
                 this.websocket = await connectionPromise;
-                this.connected = true;
+                this._setConnected(true);
                 this.log('INFO', `Connected to WebSocket server at ${this.wsEndpoint} using gar-protocol`);
 
                 this.websocket.onclose = () => {
                     this.log('WARNING', 'WebSocket connection closed.');
-                    this.connected = false;
+                    this._setConnected(false);
                     this.websocket = null;
                     this._reconnect();
                 };
                 this.websocket.onerror = (error) => {
                     this.log('ERROR', `WebSocket error: ${error.message || 'Unknown error'}`);
-                    this.connected = false;
+                    this._setConnected(false);
                     this.websocket = null;
                 };
 
@@ -396,7 +397,7 @@ class GARClient {
                 this._receiveMessages();
 
             } catch (e) {
-                this.connected = false;
+                this._setConnected(false);
                 this.websocket = null;
                 // 401 is a permanent auth rejection — retrying won't help
                 if (e.message && e.message.includes('401')) {
@@ -448,7 +449,7 @@ class GARClient {
         }
         this.log('INFO', 'Done sending messages.');
         this.stop()
-        this.connected = false;
+        this._setConnected(false);
     }
 
     /**
@@ -461,6 +462,34 @@ class GARClient {
         };
     }
 
+    /**
+     * Register a callback fired when the WS `connected` flag transitions.
+     * @param {Function} handler - Callback receiving the new boolean value
+     */
+    registerConnectedHandler(handler) {
+        this.connectedCallback = handler;
+    }
+
+    /**
+     * Clear the connected handler.
+     */
+    clearConnectedHandler() {
+        this.connectedCallback = null;
+    }
+
+    /**
+     * Internal setter that fires connectedCallback on state transitions.
+     * @param {boolean} value
+     */
+    _setConnected(value) {
+        if (this.connected === value) return;
+        this.connected = value;
+        if (this.connectedCallback) {
+            try { this.connectedCallback(value); }
+            catch (e) { this.log('ERROR', `connectedCallback threw: ${e.message}`); }
+        }
+    }
+
     /**
      * Register a callback handler for a specific message type.
      * @param {string} messageType - Type of message
@@ -796,7 +825,7 @@ class GARClient {
      * Stop the client without sending pending messages.
      */
     halt() {
-        this.connected = false;
+        this._setConnected(false);
         this.stop();
     }
 
@@ -1066,9 +1095,18 @@ class GARClient {
             this.log('INFO', 'Received Logoff from server');
             this.stop();
         } else if (msgType === 'Error') {
-            this.log('ERROR', `GAR ${message.value.message}`);
-            this.exitCode = 1;
-            this.stop();
+            // proto.gar's `error` struct carries `recoverable: bool`. Recoverable errors mean
+            // the server processed the failing message (e.g. a publish that violated some
+            // server-side check), logged it, and kept the connection alive. We dispatch the
+            // message to the user's error handler but don't tear down the client. Non-recoverable
+            // errors are followed by a server disconnect; we set exit_code + stop() so callers
+            // (CLI tools, the html_view UI) see the failure.
+            const recoverable = !!message.value.recoverable;
+            this.log(recoverable ? 'WARNING' : 'ERROR', `GAR ${message.value.message}`);
+            if (!recoverable) {
+                this.exitCode = 1;
+                this.stop();
+            }
         }
 
         this.checkHeartbeat();
@@ -1352,28 +1390,25 @@ class GARClient {
     }
 
     /**
-     * Introduce a new key if not already known and return local key ID.
+     * Introduce a new key if not already known and return local key ID. className is required;
+     * a bare introduction with no class_list can't be routed by upstream proxies.
      * @param {string} name - Key name
-     * @param {string|Array<string>|null} [className=null] - Class name(s)
+     * @param {string|Array<string>} className - Class name(s)
      * @returns {number} Local key ID
      */
-    getAndPossiblyIntroduceKeyId(name, className = null) {
+    getAndPossiblyIntroduceKeyId(name, className) {
         const existingId = this.localKeyMap.get(name);
         if (existingId !== undefined && this.invalidatedKeyIds.has(existingId)) {
             this.invalidatedKeyIds.delete(existingId);
             this.localKeyMap.delete(name);
         }
         if (!this.localKeyMap.has(name)) {
+            if (!className) throw new Error(`getAndPossiblyIntroduceKeyId: className required to introduce key "${name}"`);
             const keyId = this.localKeyCounter++;
             this.localKeyMap.set(name, keyId);
             const value = { key_id: keyId, name };
-            if (className) {
-                if (typeof className === 'string') {
-                    value.class_list = className.split(/\s+/).filter(Boolean);
-                } else if (Array.isArray(className)) {
-                    value.class_list = className;
-                }
-            }
+            if (typeof className === 'string') value.class_list = className.split(/\s+/).filter(Boolean);
+            else if (Array.isArray(className)) value.class_list = className;
             this.sendMessage({ message_type: 'KeyIntroduction', value });
         }
         return this.localKeyMap.get(name);
@@ -1415,11 +1450,24 @@ class GARClient {
     /**
      * Delete a key by name if it exists in the localKeyMap. Safe to call multiple times.
      * @param {string} keyName - Key name
+     * @param {string|null} [className=null] - If set, removes the key from this class only via
+     *     a KeyIntroduction with deleted_class set; the key may still exist on the server in
+     *     other classes and the localKeyMap entry is preserved. If unset, sends DeleteKey to
+     *     remove the key entirely and forgets the local id so a future
+     *     getAndPossiblyIntroduceKeyId(keyName) re-introduces with a fresh id.
      */
-    deleteKey(keyName) {
+    deleteKey(keyName, className = null) {
         const keyId = this.localKeyMap.get(keyName);
-        if (keyId) {
+        if (keyId === undefined) return;
+        if (className) {
+            this.sendMessage({
+                message_type: 'KeyIntroduction',
+                value: { key_id: keyId, name: keyName, deleted_class: className },
+            });
+        } else {
             this.publishDeleteKey(keyId);
+            // Forget the local id so future re-introduction allocates a new one.
+            this.localKeyMap.delete(keyName);
         }
     }
 
@@ -1463,6 +1511,10 @@ class GARClient {
      * @param {any} value - JSON-serializable value
      */
     publishRecordWithIds(keyId, topicId, value) {
+        if (value === undefined) {
+            this.log('ERROR', `publishRecordWithIds(${keyId}, ${topicId}): refusing to publish undefined — JSON.stringify would drop the "value" field and the server would reject with "Missing record 'value' field"`);
+            return;
+        }
         const updateMsg = {
             message_type: 'JSONRecordUpdate',
             value: {
@@ -1481,6 +1533,10 @@ class GARClient {
      * @param {string|null} [className=null] - Class name
      */
     publishRecord(keyName, topicName, value, className = null) {
+        if (value === undefined) {
+            this.log('ERROR', `publishRecord(${keyName}, ${topicName}): refusing to publish undefined — JSON.stringify would drop the "value" field and the server would reject with "Missing record 'value' field"`);
+            return;
+        }
         const keyId = this.getAndPossiblyIntroduceKeyId(keyName, className);
         const topicId = this.getAndPossiblyIntroduceTopicId(topicName);
         this.publishRecordWithIds(keyId, topicId, value);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsgar",
-  "version": "4.8.0",
+  "version": "4.9.1",
   "description": "A Javascript client for the GAR protocol",
   "type": "module",
   "main": "dist/gar.umd.js",
@@ -36,8 +36,11 @@
     "@eslint/json": "^0.13.2",
     "@rollup/plugin-commonjs": "^24.0.0",
     "@rollup/plugin-node-resolve": "^15.0.0",
+    "ag-grid-community": "^34.1.1",
+    "ag-grid-enterprise": "^34.1.1",
     "eslint": "^9.39.4",
     "globals": "^16.0.0",
+    "playwright": "^1.50.0",
     "rollup": "^3.0.0"
   }
 }