jsgar 4.13.2 → 4.13.4

package/dist/gar.umd.js

@@ -1179,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)
@@ -1258,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 = [];
@@ -1541,27 +1551,48 @@
         }
 
         /**
-         * Delete a key by name if it exists in the localKeyMap. Safe to call multiple times.
+         * Remove a single class from a key by sending a KeyIntroduction with deleted_class set, if the
+         * key exists in the localKeyMap. Safe to call multiple times. The key may still exist on the
+         * server in other classes, so the localKeyMap entry is preserved. Careful: every record that
+         * applied to className but to no remaining class is deleted.
          * @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.
+         * @param {string} className - Class to remove from the key
+         * @param {string|Array<string>|null} [downgradeToClassList=null] - If set, populates
+         *     key_introduction::class_list in the same message — the classes the key should apply to
+         *     alongside the removal. A single key_introduction may both add classes (class_list) and
+         *     remove one (deleted_class).
          */
-        deleteKey(keyName, className = null) {
+        deleteClass(keyName, className, downgradeToClassList = null) {
             const keyId = this.localKeyMap.get(keyName);
             if (keyId === undefined) return;
+            const value = { key_id: keyId, name: keyName, deleted_class: className };
+            if (downgradeToClassList) {
+                value.class_list = typeof downgradeToClassList === 'string'
+                    ? downgradeToClassList.split(/\s+/).filter(Boolean)
+                    : downgradeToClassList;
+            }
+            this.sendMessage({ message_type: 'KeyIntroduction', value });
+        }
+
+        /**
+         * 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, delegates to deleteClass (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, className = null) {
             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);
+                this.deleteClass(keyName, className);
+                return;
             }
+            const keyId = this.localKeyMap.get(keyName);
+            if (keyId === undefined) return;
+            this.publishDeleteKey(keyId);
+            // Forget the local id so future re-introduction allocates a new one.
+            this.localKeyMap.delete(keyName);
         }
 
         /**
@@ -1849,6 +1880,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

@@ -1172,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)
@@ -1251,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 = [];
@@ -1534,27 +1544,48 @@ class GARClient {
     }
 
     /**
-     * Delete a key by name if it exists in the localKeyMap. Safe to call multiple times.
+     * Remove a single class from a key by sending a KeyIntroduction with deleted_class set, if the
+     * key exists in the localKeyMap. Safe to call multiple times. The key may still exist on the
+     * server in other classes, so the localKeyMap entry is preserved. Careful: every record that
+     * applied to className but to no remaining class is deleted.
      * @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.
+     * @param {string} className - Class to remove from the key
+     * @param {string|Array<string>|null} [downgradeToClassList=null] - If set, populates
+     *     key_introduction::class_list in the same message — the classes the key should apply to
+     *     alongside the removal. A single key_introduction may both add classes (class_list) and
+     *     remove one (deleted_class).
      */
-    deleteKey(keyName, className = null) {
+    deleteClass(keyName, className, downgradeToClassList = null) {
         const keyId = this.localKeyMap.get(keyName);
         if (keyId === undefined) return;
+        const value = { key_id: keyId, name: keyName, deleted_class: className };
+        if (downgradeToClassList) {
+            value.class_list = typeof downgradeToClassList === 'string'
+                ? downgradeToClassList.split(/\s+/).filter(Boolean)
+                : downgradeToClassList;
+        }
+        this.sendMessage({ message_type: 'KeyIntroduction', value });
+    }
+
+    /**
+     * 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, delegates to deleteClass (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, className = null) {
         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);
+            this.deleteClass(keyName, className);
+            return;
         }
+        const keyId = this.localKeyMap.get(keyName);
+        if (keyId === undefined) return;
+        this.publishDeleteKey(keyId);
+        // Forget the local id so future re-introduction allocates a new one.
+        this.localKeyMap.delete(keyName);
     }
 
     /**
@@ -1842,6 +1873,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.2",
+  "version": "4.13.4",
   "description": "A Javascript client for the GAR protocol",
   "type": "module",
   "main": "dist/gar.umd.js",