jsgar 4.6.3 → 4.9.0

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();
         }
 
@@ -1331,13 +1360,29 @@
          * @param {boolean} [options.skipOwnershipChecks=false] - Bypass ownership validation.
          * @param {boolean} [options.requireExisting=false] - Only write to existing keys; do not create new keys.
          * @param {number} [options.clientKeyId=0] - The g::Client key ID for ownership. 0 uses the connection key.
+         * @param {string} [options.clientKeyName=''] - If non-empty, atomically introduce this g::Client key with
+         *     the message. The server creates the key and maps the remote id in one round-trip; no separate
+         *     KeyIntroduction is sent. Ignored if the name is already mapped locally (existing id is reused).
          */
-        updateActiveOwnership({ msgRef = 0, ownershipAction = 'None', skipOwnershipChecks = false, requireExisting = false, clientKeyId = 0 } = {}) {
+        updateActiveOwnership({ msgRef = 0, ownershipAction = 'None', skipOwnershipChecks = false, requireExisting = false, clientKeyId = 0, clientKeyName = '' } = {}) {
+            if (clientKeyName) {
+                const existingId = this.localKeyMap.get(clientKeyName);
+                if (existingId !== undefined) {
+                    clientKeyId = existingId;
+                    clientKeyName = '';
+                } else {
+                    clientKeyId = this.localKeyCounter++;
+                    this.localKeyMap.set(clientKeyName, clientKeyId);
+                }
+            }
             const newOwnership = { msg_ref: msgRef, ownership_action: ownershipAction, skip_ownership_checks: skipOwnershipChecks, require_existing: requireExisting, client_key_id: clientKeyId };
             const cur = this._activeOwnership;
-            if (newOwnership.msg_ref !== cur.msg_ref || newOwnership.ownership_action !== cur.ownership_action || newOwnership.skip_ownership_checks !== cur.skip_ownership_checks || newOwnership.require_existing !== cur.require_existing || newOwnership.client_key_id !== cur.client_key_id) {
+            const changed = newOwnership.msg_ref !== cur.msg_ref || newOwnership.ownership_action !== cur.ownership_action || newOwnership.skip_ownership_checks !== cur.skip_ownership_checks || newOwnership.require_existing !== cur.require_existing || newOwnership.client_key_id !== cur.client_key_id;
+            if (changed || clientKeyName) {
                 this._activeOwnership = newOwnership;
-                this.sendMessage({ message_type: 'ActiveOwnership', value: newOwnership });
+                const value = { ...newOwnership };
+                if (clientKeyName) value.client_key_name = clientKeyName;
+                this.sendMessage({ message_type: 'ActiveOwnership', value });
             }
         }
 
@@ -1405,11 +1450,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);
             }
         }
 

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();
     }
 
@@ -1325,13 +1354,29 @@ class GARClient {
      * @param {boolean} [options.skipOwnershipChecks=false] - Bypass ownership validation.
      * @param {boolean} [options.requireExisting=false] - Only write to existing keys; do not create new keys.
      * @param {number} [options.clientKeyId=0] - The g::Client key ID for ownership. 0 uses the connection key.
+     * @param {string} [options.clientKeyName=''] - If non-empty, atomically introduce this g::Client key with
+     *     the message. The server creates the key and maps the remote id in one round-trip; no separate
+     *     KeyIntroduction is sent. Ignored if the name is already mapped locally (existing id is reused).
      */
-    updateActiveOwnership({ msgRef = 0, ownershipAction = 'None', skipOwnershipChecks = false, requireExisting = false, clientKeyId = 0 } = {}) {
+    updateActiveOwnership({ msgRef = 0, ownershipAction = 'None', skipOwnershipChecks = false, requireExisting = false, clientKeyId = 0, clientKeyName = '' } = {}) {
+        if (clientKeyName) {
+            const existingId = this.localKeyMap.get(clientKeyName);
+            if (existingId !== undefined) {
+                clientKeyId = existingId;
+                clientKeyName = '';
+            } else {
+                clientKeyId = this.localKeyCounter++;
+                this.localKeyMap.set(clientKeyName, clientKeyId);
+            }
+        }
         const newOwnership = { msg_ref: msgRef, ownership_action: ownershipAction, skip_ownership_checks: skipOwnershipChecks, require_existing: requireExisting, client_key_id: clientKeyId };
         const cur = this._activeOwnership;
-        if (newOwnership.msg_ref !== cur.msg_ref || newOwnership.ownership_action !== cur.ownership_action || newOwnership.skip_ownership_checks !== cur.skip_ownership_checks || newOwnership.require_existing !== cur.require_existing || newOwnership.client_key_id !== cur.client_key_id) {
+        const changed = newOwnership.msg_ref !== cur.msg_ref || newOwnership.ownership_action !== cur.ownership_action || newOwnership.skip_ownership_checks !== cur.skip_ownership_checks || newOwnership.require_existing !== cur.require_existing || newOwnership.client_key_id !== cur.client_key_id;
+        if (changed || clientKeyName) {
             this._activeOwnership = newOwnership;
-            this.sendMessage({ message_type: 'ActiveOwnership', value: newOwnership });
+            const value = { ...newOwnership };
+            if (clientKeyName) value.client_key_name = clientKeyName;
+            this.sendMessage({ message_type: 'ActiveOwnership', value });
         }
     }
 
@@ -1399,11 +1444,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);
         }
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsgar",
-  "version": "4.6.3",
+  "version": "4.9.0",
   "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"
   }
 }