jsgar 2.1.0 → 3.0.0

package/dist/gar.umd.js

@@ -50,7 +50,7 @@
             this.user = user;
             this.working_namespace = working_namespace;
             this.heartbeatTimeoutInterval = heartbeatTimeoutInterval;
-            this.version = 650704;
+            this.version = 650705;
 
             if (typeof window !== 'undefined' && window.location) {
                 this.application = window.location.href;
@@ -589,30 +589,76 @@
         }
 
         /**
-         * Send a subscription request using local IDs.
+         * Send an already-formatted subscription message
+         * @param {object} subscriptionMessageValue - json representation of the gar `subscribe` struct
+         */
+        subscribeFormatted(subscriptionMessageValue) {
+            const subMsg = {
+                message_type: 'Subscribe',
+                value: subscriptionMessageValue,
+            };
+            this.sendMessage(subMsg);
+        }
+
+        /**
+         * Send a subscription request
          * @param {string} name - Subscription name
-         * @param {string} [mode='Streaming'] - Subscription mode
+         * @param {string} [subscriptionMode='Streaming'] - Subscription mode
          * @param {string|Array<string>|null} [keyName=null] - Key name(s)
          * @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
-         * @param {string|null} [topicFilter=null] - Topic filter regex
-         * @param {boolean} [allMatchingKeys=false] - Retrieve all matching keys
-         * @param subscriptionGroup - Subscription group ID for isolating callbacks
+         * @param {string|null} [keyFilter=null] - Key filter regex (cannot use with keyName)
+         * @param {string|null} [topicFilter=null] - Topic filter regex (cannot use with topicName)
+         * @param {string|null} [excludeKeyFilter=null] - Exclude key filter regex (cannot use with keyName)
+         * @param {string|null} [excludeTopicFilter=null] - Exclude topic filter regex (cannot use with topicName)
+         * @param {string|null} [maxHistory] - Maximum history to include
+         * @param {boolean} [includeReferencedKeys=false] - Add keys from key references in matched records
+         * @param {boolean} [includeReferencingKeys=false] - Add keys that have one or more records referencing any matched keys
+         * @param {boolean} [includeAllNamespace=false] - Include keys and topics from all namespaces
+         * @param {string|null} [workingNamespace] - Namespace for matching relative paths
+         * @param {string|null} [density] - For performance tuning
+         * @param {number} [subscriptionGroup=0] - Subscription group ID for isolating callbacks
+         * @param {string|null} [subscriptionSet] - Subscription set identifier
          * @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)
          */
         subscribe(
             name,
-            mode = 'Streaming',
+            subscriptionMode = 'Streaming',
             keyName = null,
             topicName = null,
             className = null,
             keyFilter = null,
             topicFilter = null,
-            allMatchingKeys = false,
+            excludeKeyFilter = null,
+            excludeTopicFilter = null,
+            maxHistory = null,
+            includeReferencedKeys = false,
+            includeReferencingKeys = false,
+            includeAllNamespace = false,
+            workingNamespace = null,
+            density = null,
             subscriptionGroup = 0,
-            snapshotSizeLimit = 0
+            subscriptionSet = null,
+            snapshotSizeLimit = 0,
+            nagleInterval = 0,
+            limit = 0
         ) {
+            // Validate mutually exclusive parameters
+            if (keyName && (keyFilter || excludeKeyFilter)) {
+                throw new Error('keyName cannot be used with keyFilter or excludeKeyFilter');
+            }
+            
+            if (topicName && (topicFilter || excludeTopicFilter)) {
+                throw new Error('topicName cannot be used with topicFilter or excludeTopicFilter');
+            }
+
+            // Validate limit parameter usage
+            if (limit > 0 && subscriptionMode === 'Streaming') {
+                throw new Error('limit cannot be used with streaming subscriptions');
+            }
+
             // Convert className to array
             let classList = null;
             if (typeof className === 'string') {
@@ -641,23 +687,118 @@
             }
             const topicIdList = topicNames.map(x => this.getAndPossiblyIntroduceTopicId(x));
 
-            const subMsg = {
-                message_type: 'Subscribe',
-                value: {
-                    subscription_mode: mode,
-                    all_matching_keys: allMatchingKeys,
-                    snapshot_size_limit: snapshotSizeLimit,
-                    nagle_interval: 0,
-                    name,
-                    key_id_list: keyIdList,
-                    topic_id_list: topicIdList,
-                    class_list: classList,
-                    key_filter: keyFilter,
-                    topic_filter: topicFilter,
-                    subscription_group: subscriptionGroup
-                }
+            // Build subscription message, filtering out null/undefined values
+            const valueDict = {
+                subscription_mode: subscriptionMode,
+                name,
             };
-            this.sendMessage(subMsg);
+            
+            // Add optional fields only if they have values
+            if (subscriptionSet) {
+                valueDict.subscription_set = subscriptionSet;
+            }
+            if (maxHistory) {
+                valueDict.max_history = maxHistory;
+            }
+            if (snapshotSizeLimit > 0) {
+                valueDict.snapshot_size_limit = snapshotSizeLimit;
+            }
+            if (nagleInterval > 0) {
+                valueDict.nagle_interval = nagleInterval;
+            }
+            if (subscriptionGroup > 0) {
+                valueDict.subscription_group = subscriptionGroup;
+            }
+            if (density) {
+                valueDict.density = density;
+            }
+            if (includeReferencedKeys) {
+                valueDict.include_referenced_keys = includeReferencedKeys;
+            }
+            if (includeReferencingKeys) {
+                valueDict.include_referencing_keys = includeReferencingKeys;
+            }
+            if (includeAllNamespace) {
+                valueDict.include_all_namespace = includeAllNamespace;
+            }
+            if (limit > 0) {
+                valueDict.limit = limit;
+            }
+            if (keyIdList.length > 0) {
+                valueDict.key_id_list = keyIdList;
+            }
+            if (topicIdList.length > 0) {
+                valueDict.topic_id_list = topicIdList;
+            }
+            if (classList) {
+                valueDict.class_list = classList;
+            }
+            if (keyFilter) {
+                valueDict.key_filter = keyFilter;
+            }
+            if (excludeKeyFilter) {
+                valueDict.exclude_key_filter = excludeKeyFilter;
+            }
+            if (topicFilter) {
+                valueDict.topic_filter = topicFilter;
+            }
+            if (excludeTopicFilter) {
+                valueDict.exclude_topic_filter = excludeTopicFilter;
+            }
+            if (workingNamespace) {
+                valueDict.working_namespace = workingNamespace;
+            }
+
+            this.subscribeFormatted(valueDict);
+        }
+
+        /**
+         * Wrapper to `subscribe` with a smaller set of arguments.
+         * @param {string} name - Subscription name
+         * @param {string} [subscriptionMode='Streaming'] - Subscription mode
+         * @param {number} [subscriptionGroup=0] - Subscription group ID for isolating callbacks
+         * @param {number} [snapshotSizeLimit=0] - Limit snapshot size
+         * @param {string|Array<string>|null} [keyName=null] - Key name(s)
+         * @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)
+         * @param {string|null} [topicFilter=null] - Topic filter regex (cannot use with topicName)
+         * @param {string|null} [excludeKeyFilter=null] - Exclude key filter regex (cannot use with keyName)
+         * @param {string|null} [excludeTopicFilter=null] - Exclude topic filter regex (cannot use with topicName)
+         */
+        subscribeCommon(
+            name,
+            subscriptionMode = 'Streaming',
+            subscriptionGroup = 0,
+            snapshotSizeLimit = 0,
+            keyName = null,
+            topicName = null,
+            className = null,
+            keyFilter = null,
+            topicFilter = null,
+            excludeKeyFilter = null,
+            excludeTopicFilter = null,
+        ) {
+            this.subscribe(
+                name,
+                subscriptionMode,
+                keyName,
+                topicName,
+                className,
+                keyFilter,
+                topicFilter,
+                excludeKeyFilter,
+                excludeTopicFilter,
+                null,
+                false,
+                false,
+                false,
+                null,
+                null,
+                subscriptionGroup,
+                null,
+                snapshotSizeLimit
+            );
         }
 
         /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsgar",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "description": "A Javascript client for the GAR protocol",
   "type": "module",
   "main": "dist/gar.umd.js",
@@ -27,7 +27,7 @@
     "@eslint/json": "^0.12.0",
     "@rollup/plugin-commonjs": "^24.0.0",
     "@rollup/plugin-node-resolve": "^15.0.0",
-    "eslint": "^9.25.0",
+    "eslint": "^9.33.0",
     "globals": "^16.0.0",
     "rollup": "^3.0.0"
   }