Merge branch 'release/3.2.0'

Author: msqr

lib/net/jsonClientSupport.d.ts

@@ -40,8 +40,9 @@ export default abstract class JsonClientSupport<API extends UrlHelper, T> {
      *
      * @param url the URL to request.
      * @param signUrl the URL to sign (might be different to `url` if a proxy is used)
+     * @param delay an optional number of milliseconds to sleep before initiating the request
      * @returns a function that accepts a callback argument
      */
-    protected requestor<V>(url: string, signUrl?: string): (cb: LoaderDataCallbackFn<V>) => void;
+    protected requestor<V>(url: string, signUrl?: string, delay?: number): (cb: LoaderDataCallbackFn<V>) => void;
 }
 //# sourceMappingURL=jsonClientSupport.d.ts.map

lib/net/jsonClientSupport.d.ts.map

@@ -1,4 +1,4 @@
-// https://github.com/SolarNetwork/sn-api-core-js Version 3.1.2. Copyright 2025 SolarNetwork Foundation.
+// https://github.com/SolarNetwork/sn-api-core-js Version 3.2.0. Copyright 2025 SolarNetwork Foundation.
 'use strict';
 
 /**
@@ -11747,11 +11747,12 @@ class JsonClientSupport {
      *
      * @param url the URL to request.
      * @param signUrl the URL to sign (might be different to `url` if a proxy is used)
+     * @param delay an optional number of milliseconds to sleep before initiating the request
      * @returns a function that accepts a callback argument
      */
-    requestor(url, signUrl) {
+    requestor(url, signUrl, delay) {
         const auth = this.authBuilder;
-        return (cb) => {
+        const fn = (cb) => {
             const headers = {
                 Accept: "application/json",
             };
@@ -11788,6 +11789,14 @@ class JsonClientSupport {
                 }, errorHandler);
             }, errorHandler);
         };
+        if (delay && delay > 0) {
+            return (cb) => {
+                setTimeout(() => {
+                    fn.call(this, cb);
+                }, delay);
+            };
+        }
+        return fn;
     }
 }
 
@@ -12890,6 +12899,7 @@ class ControlToggler {
 }
 
 const DEFAULT_PAGE_SIZE = 1000;
+const DEFAULT_JITTER = 150;
 /**
  * An enumeration of loader state values.
  */
@@ -12945,6 +12955,11 @@ class DatumLoader extends JsonClientSupport {
      * results, followed by parallel requests for the remaining pages.
      */
     #concurrency;
+    /**
+     * When > 0 then add a random amount of milliseconds up to this amount before initiating
+     * parallel requests (thus #concurrency must also be configured).
+     */
+    #jitter;
     /**
      * A queue to use for parallel mode, when `concurrency` configured > 0.
      */
@@ -12971,17 +12986,27 @@ class DatumLoader extends JsonClientSupport {
         this.#readingsMode = false;
         this.#proxyUrl = null;
         this.#concurrency = 0;
+        this.#jitter = DEFAULT_JITTER;
         this.#state = DatumLoaderState.Ready;
     }
     concurrency(value) {
         if (value === undefined) {
             return this.#concurrency;
         }
-        if (!isNaN(value) && Number(value) > 0) {
+        if (!isNaN(value) && Number(value) >= 0) {
             this.#concurrency = Number(value);
         }
         return this;
     }
+    jitter(value) {
+        if (value === undefined) {
+            return this.#jitter;
+        }
+        if (!isNaN(value) && Number(value) >= 0) {
+            this.#jitter = Number(value);
+        }
+        return this;
+    }
     callback(value) {
         if (value === undefined) {
             return this.#callback;
@@ -13138,7 +13163,11 @@ class DatumLoader extends JsonClientSupport {
         const reqUrl = this.#proxyUrl
             ? url.replace(/^[^:]+:\/\/[^/]+/, this.#proxyUrl)
             : url;
-        const query = this.requestor(reqUrl, url);
+        // add delay for parallel mode if jitter configured
+        const delay = q && this.#jitter > 0
+            ? Math.floor(Math.random() * this.#jitter) + 1
+            : 0;
+        const query = this.requestor(reqUrl, url, delay);
         const handler = (error, data) => {
             if (error) {
                 if (!q) {

lib/net/jsonClientSupport.js

@@ -66,6 +66,23 @@ export default class DatumLoader extends JsonClientSupport<SolarQueryApi, Datum[
      * @returns this object
      */
     concurrency(value: number): this;
+    /**
+     * Get the concurrency jitter value to use for parallel requests.
+     *
+     * @returns the current concurrency jitter value (milliseconds); defaults to `150`
+     */
+    jitter(): number;
+    /**
+     * Set the concurrency jitter amount to use for parallel requests.
+     *
+     * When parallel mode is enabled by setting `concurrency()` to a positive value, a random amount
+     * of "pause" time can be added before parallel requests are made by configuring this
+     * to a positive value. This can be helpful to avoid API rate limiting errors.
+     *
+     * @param value the concurrency jitter amount to use, in milliseconds, or `0` to disable
+     * @returns this object
+     */
+    jitter(value: number): this;
     /**
      * Get the optional callback function.
      *