jsgar 4.10.0 → 4.13.2

package/dist/gar.umd.js

@@ -4,6 +4,7 @@
     (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.GARClient = {}));
 })(this, (function (exports) { 'use strict';
 
+    var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
     /**
      * A client implementation for the Generic Active Records (GAR) protocol using WebSockets.
      * See trsgar.js for example usage.
@@ -805,25 +806,27 @@
 
         async _ensureWebSocketCtor() {
             // Return a WebSocket constructor for current environment.
-            // Prefer any existing globalThis.WebSocket (browser or pre-set in Node).
-            if (typeof globalThis !== 'undefined' && globalThis.WebSocket) {
-                return globalThis.WebSocket;
-            }
-            // Node.js: resolve 'ws' at runtime
+            // In Node, always prefer the 'ws' package over globalThis.WebSocket.
+            // Node ≥21 ships a browser-spec WebSocket on globalThis that ignores the
+            // third-arg options object (rejectUnauthorized, headers, agent, etc.),
+            // which breaks self-signed certs and custom TLS configuration.
             const isNode = typeof process !== 'undefined' && process.versions && process.versions.node;
             if (isNode) {
                 try {
-                    // createRequire works in both ESM and CJS; resolves from cwd
+                    // Anchor resolution at this module so ws is found regardless of cwd.
                     const { createRequire } = await import('node:module');
-                    const req = createRequire(process.cwd() + '/');
+                    const req = createRequire((typeof document === 'undefined' && typeof location === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : typeof document === 'undefined' ? location.href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('gar.umd.js', document.baseURI).href)));
                     const mod = req('ws');
                     const WS = mod.default || mod.WebSocket || mod;
-                    globalThis.WebSocket = WS;
                     return WS;
                 } catch {
                     throw new Error("'ws' module is required in Node.js environment. Please install it: npm install ws");
                 }
             }
+            // Browser: use the platform WebSocket.
+            if (typeof globalThis !== 'undefined' && globalThis.WebSocket) {
+                return globalThis.WebSocket;
+            }
             throw new Error('WebSocket constructor not found in this environment');
         }
 
@@ -849,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;
+                }
+            }
         }
 
         /**
@@ -976,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) {
@@ -1092,13 +1127,8 @@
                     }
                 }
 
-                // If there is a batch handler, call it
-                if (hasBatchHandler) {
-                    const batchHandler = this.messageHandlers.get(batchHandlerKey);
-                    if (batchHandler) {
-                        batchHandler(message);
-                    }
-                }
+                // If there is a batch handler the generic dispatch at the bottom of this method will
+                // invoke it — do not call it explicitly here (would double-dispatch).
             } else if (msgType === "ActiveSubscription") {
                 this.activeSubscriptionGroup = message["value"]["subscription_group"];
             } else if (msgType === 'Logoff') {
@@ -1140,9 +1170,15 @@
         }
 
         /**
-         * Send a subscription request
-         * @param {string} name - Subscription name
-         * @param {string} [subscriptionMode='Streaming'] - Subscription mode
+         * Send a subscription request from a named-options object — the canonical entry point.
+         * Options are passed by name, so adding a new field can never positionally misalign an
+         * existing caller (the failure mode of the positional `subscribe()` shim below). Owns the
+         * convenience layer: mutual-exclusion assertions, string→single-element-list coercion, and
+         * keyName/topicName/className resolution into the wire `key_id_list`/`topic_id_list`/
+         * `class_list`. Produces a `g::proto::subscribe` value dict and hands it to subscribeFormatted.
+         * @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>|null} [topicName=null] - Topic name(s)
          * @param {string|Array<string>|null} [className=null] - Class name(s)
@@ -1153,6 +1189,7 @@
          * @param {string|null} [maxHistory] - Maximum history to include
          * @param {boolean} [excludeDerived=false] - Exclude derived topics (derived topics are included by default)
          * @param {boolean} [includeHeavy=false] - Include heavy derived topics (comprehensions, array-typed, heavy functions)
+         * @param {boolean} [includeExplicit=false] - Include explicit-only topics (the `explicit` attribute, defaulted on for once-gated topics; excluded by default like includeHeavy)
          * @param {boolean} [trimDefaultValues=false] - Trim records containing default values from the snapshot
          * @param {string|null} [workingNamespace] - Namespace for matching relative paths
          * @param {string|Array<string>|null} [restrictNamespace] - Restricts topics and keys to children of these namespaces (union). Defaults to the working namespace. Use ["::"] for root / no restriction.
@@ -1165,7 +1202,7 @@
          * @param {number} [limit=0] - Limits records in initial snapshot (0 = all)
          * @param {string|Array<string>|null} [referencingClassList=null] - Referencing class name(s); if provided, include referencing keys and records per proto.gar subscribe.referencing_class_list
          */
-        subscribe(
+        subscribeOptions({
             name,
             subscriptionMode = 'Streaming',
             keyName = null,
@@ -1178,6 +1215,7 @@
             maxHistory = null,
             excludeDerived = false,
             includeHeavy = false,
+            includeExplicit = false,
             trimDefaultValues = false,
             workingNamespace = null,
             restrictNamespace = null,
@@ -1189,7 +1227,7 @@
             nagleInterval = 0,
             limit = 0,
             referencingClassList = null
-        ) {
+        } = {}) {
             // Validate mutually exclusive parameters
             if (keyName && (keyFilter || excludeKeyFilter)) {
                 throw new Error('keyName cannot be used with keyFilter or excludeKeyFilter');
@@ -1271,6 +1309,9 @@
             if (includeHeavy) {
                 valueDict.include_heavy = includeHeavy;
             }
+            if (includeExplicit) {
+                valueDict.include_explicit = includeExplicit;
+            }
             if (restrictNamespace) {
                 valueDict.restrict_namespace = typeof restrictNamespace === 'string' ? [restrictNamespace] : restrictNamespace;
             }
@@ -1314,6 +1355,47 @@
             this.subscribeFormatted(valueDict);
         }
 
+        /**
+         * Positional compatibility shim — packs its arguments by name and delegates to
+         * subscribeOptions(). Prefer subscribeOptions({ ... }) in new code: its named signature makes
+         * the positional-argument misalignment trap impossible. The parameter order here is frozen for
+         * existing callers — never insert a new parameter mid-list; add new options to subscribeOptions.
+         */
+        subscribe(
+            name,
+            subscriptionMode = 'Streaming',
+            keyName = null,
+            topicName = null,
+            className = null,
+            keyFilter = null,
+            topicFilter = null,
+            excludeKeyFilter = null,
+            excludeTopicFilter = null,
+            maxHistory = null,
+            excludeDerived = false,
+            includeHeavy = false,
+            includeExplicit = false,
+            trimDefaultValues = false,
+            workingNamespace = null,
+            restrictNamespace = null,
+            excludeNamespace = null,
+            density = null,
+            subscriptionGroup = 0,
+            subscriptionSet = null,
+            snapshotSizeLimit = 0,
+            nagleInterval = 0,
+            limit = 0,
+            referencingClassList = null
+        ) {
+            this.subscribeOptions({
+                name, subscriptionMode, keyName, topicName, className, keyFilter, topicFilter,
+                excludeKeyFilter, excludeTopicFilter, maxHistory, excludeDerived, includeHeavy,
+                includeExplicit, trimDefaultValues, workingNamespace, restrictNamespace, excludeNamespace,
+                density, subscriptionGroup, subscriptionSet, snapshotSizeLimit, nagleInterval, limit,
+                referencingClassList,
+            });
+        }
+
         /**
          * Wrapper to `subscribe` with a smaller set of arguments.
          * @param {string} name - Subscription name
@@ -1351,16 +1433,17 @@
                 topicFilter,
                 excludeKeyFilter,
                 excludeTopicFilter,
-                null,
-                false,
-                false,
-                false,
-                null,
-                null,
-                null,
-                null,
+                null,              // maxHistory
+                false,             // excludeDerived
+                false,             // includeHeavy
+                false,             // includeExplicit
+                false,             // trimDefaultValues
+                null,              // workingNamespace
+                null,              // restrictNamespace
+                null,              // excludeNamespace
+                null,              // density
                 subscriptionGroup,
-                null,
+                null,              // subscriptionSet
                 snapshotSizeLimit
             );
         }
@@ -1692,15 +1775,16 @@
                         null,
                         null,
                         null,
-                        null,
-                        false,
-                        false,
-                        false,
-                        'g::deployment::Server',
-                        null,
-                        null,
-                        null,
-                        subscriptionGroupServerRecords,
+                        null,                    // maxHistory
+                        false,                   // excludeDerived
+                        false,                   // includeHeavy
+                        false,                   // includeExplicit
+                        false,                   // trimDefaultValues
+                        'g::deployment::Server', // workingNamespace
+                        null,                    // restrictNamespace
+                        null,                    // excludeNamespace
+                        null,                    // density
+                        subscriptionGroupServerRecords, // subscriptionGroup
                     );
                 };
 
@@ -1742,15 +1826,16 @@
                     null,
                     null,
                     null,
-                    null,
-                    false,
-                    false,
-                    false,
-                    'g::deployment::RecordFilter',
-                    null,
-                    null,
-                    null,
-                    subscriptionGroupServerKeys,
+                    null,                          // maxHistory
+                    false,                         // excludeDerived
+                    false,                         // includeHeavy
+                    false,                         // includeExplicit
+                    false,                         // trimDefaultValues
+                    'g::deployment::RecordFilter', // workingNamespace
+                    null,                          // restrictNamespace
+                    null,                          // excludeNamespace
+                    null,                          // density
+                    subscriptionGroupServerKeys,   // subscriptionGroup
                 );
 
                 // Timeout handling

package/gar.js

@@ -799,25 +799,27 @@ class GARClient {
 
     async _ensureWebSocketCtor() {
         // Return a WebSocket constructor for current environment.
-        // Prefer any existing globalThis.WebSocket (browser or pre-set in Node).
-        if (typeof globalThis !== 'undefined' && globalThis.WebSocket) {
-            return globalThis.WebSocket;
-        }
-        // Node.js: resolve 'ws' at runtime
+        // In Node, always prefer the 'ws' package over globalThis.WebSocket.
+        // Node ≥21 ships a browser-spec WebSocket on globalThis that ignores the
+        // third-arg options object (rejectUnauthorized, headers, agent, etc.),
+        // which breaks self-signed certs and custom TLS configuration.
         const isNode = typeof process !== 'undefined' && process.versions && process.versions.node;
         if (isNode) {
             try {
-                // createRequire works in both ESM and CJS; resolves from cwd
+                // Anchor resolution at this module so ws is found regardless of cwd.
                 const { createRequire } = await import('node:module');
-                const req = createRequire(process.cwd() + '/');
+                const req = createRequire(import.meta.url);
                 const mod = req('ws');
                 const WS = mod.default || mod.WebSocket || mod;
-                globalThis.WebSocket = WS;
                 return WS;
             } catch {
                 throw new Error("'ws' module is required in Node.js environment. Please install it: npm install ws");
             }
         }
+        // Browser: use the platform WebSocket.
+        if (typeof globalThis !== 'undefined' && globalThis.WebSocket) {
+            return globalThis.WebSocket;
+        }
         throw new Error('WebSocket constructor not found in this environment');
     }
 
@@ -843,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;
+            }
+        }
     }
 
     /**
@@ -970,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) {
@@ -1086,13 +1120,8 @@ class GARClient {
                 }
             }
 
-            // If there is a batch handler, call it
-            if (hasBatchHandler) {
-                const batchHandler = this.messageHandlers.get(batchHandlerKey);
-                if (batchHandler) {
-                    batchHandler(message);
-                }
-            }
+            // If there is a batch handler the generic dispatch at the bottom of this method will
+            // invoke it — do not call it explicitly here (would double-dispatch).
         } else if (msgType === "ActiveSubscription") {
             this.activeSubscriptionGroup = message["value"]["subscription_group"]
         } else if (msgType === 'Logoff') {
@@ -1134,9 +1163,15 @@ class GARClient {
     }
 
     /**
-     * Send a subscription request
-     * @param {string} name - Subscription name
-     * @param {string} [subscriptionMode='Streaming'] - Subscription mode
+     * Send a subscription request from a named-options object — the canonical entry point.
+     * Options are passed by name, so adding a new field can never positionally misalign an
+     * existing caller (the failure mode of the positional `subscribe()` shim below). Owns the
+     * convenience layer: mutual-exclusion assertions, string→single-element-list coercion, and
+     * keyName/topicName/className resolution into the wire `key_id_list`/`topic_id_list`/
+     * `class_list`. Produces a `g::proto::subscribe` value dict and hands it to subscribeFormatted.
+     * @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>|null} [topicName=null] - Topic name(s)
      * @param {string|Array<string>|null} [className=null] - Class name(s)
@@ -1147,6 +1182,7 @@ class GARClient {
      * @param {string|null} [maxHistory] - Maximum history to include
      * @param {boolean} [excludeDerived=false] - Exclude derived topics (derived topics are included by default)
      * @param {boolean} [includeHeavy=false] - Include heavy derived topics (comprehensions, array-typed, heavy functions)
+     * @param {boolean} [includeExplicit=false] - Include explicit-only topics (the `explicit` attribute, defaulted on for once-gated topics; excluded by default like includeHeavy)
      * @param {boolean} [trimDefaultValues=false] - Trim records containing default values from the snapshot
      * @param {string|null} [workingNamespace] - Namespace for matching relative paths
      * @param {string|Array<string>|null} [restrictNamespace] - Restricts topics and keys to children of these namespaces (union). Defaults to the working namespace. Use ["::"] for root / no restriction.
@@ -1159,7 +1195,7 @@ class GARClient {
      * @param {number} [limit=0] - Limits records in initial snapshot (0 = all)
      * @param {string|Array<string>|null} [referencingClassList=null] - Referencing class name(s); if provided, include referencing keys and records per proto.gar subscribe.referencing_class_list
      */
-    subscribe(
+    subscribeOptions({
         name,
         subscriptionMode = 'Streaming',
         keyName = null,
@@ -1172,6 +1208,7 @@ class GARClient {
         maxHistory = null,
         excludeDerived = false,
         includeHeavy = false,
+        includeExplicit = false,
         trimDefaultValues = false,
         workingNamespace = null,
         restrictNamespace = null,
@@ -1183,7 +1220,7 @@ class GARClient {
         nagleInterval = 0,
         limit = 0,
         referencingClassList = null
-    ) {
+    } = {}) {
         // Validate mutually exclusive parameters
         if (keyName && (keyFilter || excludeKeyFilter)) {
             throw new Error('keyName cannot be used with keyFilter or excludeKeyFilter');
@@ -1265,6 +1302,9 @@ class GARClient {
         if (includeHeavy) {
             valueDict.include_heavy = includeHeavy;
         }
+        if (includeExplicit) {
+            valueDict.include_explicit = includeExplicit;
+        }
         if (restrictNamespace) {
             valueDict.restrict_namespace = typeof restrictNamespace === 'string' ? [restrictNamespace] : restrictNamespace;
         }
@@ -1308,6 +1348,47 @@ class GARClient {
         this.subscribeFormatted(valueDict);
     }
 
+    /**
+     * Positional compatibility shim — packs its arguments by name and delegates to
+     * subscribeOptions(). Prefer subscribeOptions({ ... }) in new code: its named signature makes
+     * the positional-argument misalignment trap impossible. The parameter order here is frozen for
+     * existing callers — never insert a new parameter mid-list; add new options to subscribeOptions.
+     */
+    subscribe(
+        name,
+        subscriptionMode = 'Streaming',
+        keyName = null,
+        topicName = null,
+        className = null,
+        keyFilter = null,
+        topicFilter = null,
+        excludeKeyFilter = null,
+        excludeTopicFilter = null,
+        maxHistory = null,
+        excludeDerived = false,
+        includeHeavy = false,
+        includeExplicit = false,
+        trimDefaultValues = false,
+        workingNamespace = null,
+        restrictNamespace = null,
+        excludeNamespace = null,
+        density = null,
+        subscriptionGroup = 0,
+        subscriptionSet = null,
+        snapshotSizeLimit = 0,
+        nagleInterval = 0,
+        limit = 0,
+        referencingClassList = null
+    ) {
+        this.subscribeOptions({
+            name, subscriptionMode, keyName, topicName, className, keyFilter, topicFilter,
+            excludeKeyFilter, excludeTopicFilter, maxHistory, excludeDerived, includeHeavy,
+            includeExplicit, trimDefaultValues, workingNamespace, restrictNamespace, excludeNamespace,
+            density, subscriptionGroup, subscriptionSet, snapshotSizeLimit, nagleInterval, limit,
+            referencingClassList,
+        });
+    }
+
     /**
      * Wrapper to `subscribe` with a smaller set of arguments.
      * @param {string} name - Subscription name
@@ -1345,16 +1426,17 @@ class GARClient {
             topicFilter,
             excludeKeyFilter,
             excludeTopicFilter,
-            null,
-            false,
-            false,
-            false,
-            null,
-            null,
-            null,
-            null,
+            null,              // maxHistory
+            false,             // excludeDerived
+            false,             // includeHeavy
+            false,             // includeExplicit
+            false,             // trimDefaultValues
+            null,              // workingNamespace
+            null,              // restrictNamespace
+            null,              // excludeNamespace
+            null,              // density
             subscriptionGroup,
-            null,
+            null,              // subscriptionSet
             snapshotSizeLimit
         );
     }
@@ -1686,15 +1768,16 @@ class GARClient {
                     null,
                     null,
                     null,
-                    null,
-                    false,
-                    false,
-                    false,
-                    'g::deployment::Server',
-                    null,
-                    null,
-                    null,
-                    subscriptionGroupServerRecords,
+                    null,                    // maxHistory
+                    false,                   // excludeDerived
+                    false,                   // includeHeavy
+                    false,                   // includeExplicit
+                    false,                   // trimDefaultValues
+                    'g::deployment::Server', // workingNamespace
+                    null,                    // restrictNamespace
+                    null,                    // excludeNamespace
+                    null,                    // density
+                    subscriptionGroupServerRecords, // subscriptionGroup
                 );
             };
 
@@ -1736,15 +1819,16 @@ class GARClient {
                 null,
                 null,
                 null,
-                null,
-                false,
-                false,
-                false,
-                'g::deployment::RecordFilter',
-                null,
-                null,
-                null,
-                subscriptionGroupServerKeys,
+                null,                          // maxHistory
+                false,                         // excludeDerived
+                false,                         // includeHeavy
+                false,                         // includeExplicit
+                false,                         // trimDefaultValues
+                'g::deployment::RecordFilter', // workingNamespace
+                null,                          // restrictNamespace
+                null,                          // excludeNamespace
+                null,                          // density
+                subscriptionGroupServerKeys,   // subscriptionGroup
             );
 
             // Timeout handling

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsgar",
-  "version": "4.10.0",
+  "version": "4.13.2",
   "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",