@adaptic/utils 0.0.991 → 0.0.993

package/README.md

@@ -1,15 +1,27 @@
 # @adaptic/utils
 
-Last updated: 20 Feb 2025
-
 A comprehensive utility library for financial data processing, time manipulation, and formatting.
 
 NPM repo: https://www.npmjs.com/package/@adaptic/utils
 
+## Branch Model
+
+This repo has two publish lineages:
+
+- `master` -> `@adaptic/utils@0.1.x` on npm dist-tag `latest`. What external
+  unpinned `npm install @adaptic/utils` will pull.
+- `stable-release` -> `@adaptic/utils@0.0.x` (0.0.992+) on npm dist-tag
+  `stable`. What `engine` and `backend-legacy` actually consume via pinned
+  versions.
+
+All new work lands on `stable-release`. `master` is only updated when
+intentionally cutting a 0.1.x patch for legacy external consumers.
+
 ## Installation
 
 ```bash
-npm install @adaptic/utils
+npm install @adaptic/utils       # 0.1.x from master
+npm install @adaptic/utils@stable # 0.0.x from stable-release (engine pins this)
 ```
 
 ## Usage

package/dist/index.cjs

@@ -2691,6 +2691,48 @@ class AlpacaMarketDataAPI extends require$$0$1.EventEmitter {
     };
     reconnectAttempts = {};
     reconnectTimers = {};
+    /**
+     * Wall-clock timestamp of the most recent Alpaca app-level error code
+     * 406 ("connection limit exceeded") received on each stream. Used by
+     * {@link scheduleReconnect} to apply a long backoff with jitter rather
+     * than the normal sub-second exponential ramp — without this, hitting
+     * Alpaca's account-wide concurrent-connection cap (typical for blue/green
+     * deploy rollovers where the old pod's WS slots haven't been released
+     * yet) produced a 10-attempt retry storm that compounded the slot
+     * pressure and consumed the per-account connection quota across the
+     * organisation.
+     *
+     * Cleared once the long-backoff retry is scheduled so that subsequent
+     * normal failures fall back to the standard sub-second exponential.
+     *
+     * @see CONNECTION_LIMIT_BACKOFF_MS / CONNECTION_LIMIT_BACKOFF_JITTER_MS
+     */
+    lastConnectionLimitAt = {};
+    /**
+     * Five-minute base backoff after Alpaca's app-level 406. Long enough
+     * for Alpaca's server-side cleanup to release stale slots in typical
+     * rollover scenarios; short enough that an operator doesn't need to
+     * intervene. Mirrors the equivalent MassiveClient
+     * `MAX_CONNECTIONS_RETRY_DELAY_MS` (engine v1.0.59) so both providers
+     * behave identically under the same failure mode.
+     */
+    CONNECTION_LIMIT_BACKOFF_MS = 5 * 60_000;
+    /**
+     * ±30 s of uniform jitter on the connection-limit backoff. Prevents
+     * a thundering-herd retry when all three streams (stock / option /
+     * crypto) hit 406 simultaneously during a deploy rollover — without
+     * jitter they'd all retry at the same wall-clock instant and could
+     * re-trip the account cap together.
+     */
+    CONNECTION_LIMIT_BACKOFF_JITTER_MS = 30_000;
+    /**
+     * Recency window within which a 406 is considered "still applicable"
+     * to a subsequent reconnect-schedule call. The 406 message handler
+     * stamps {@link lastConnectionLimitAt} and the `close` handler fires
+     * shortly afterwards (sub-second typically) — the window is wide
+     * enough to absorb scheduling delays without false-positives.
+     */
+    CONNECTION_LIMIT_RECENCY_MS = 30_000;
     setMode(mode = "production") {
         if (mode === "sandbox") {
             // sandbox mode
@@ -2822,6 +2864,18 @@ class AlpacaMarketDataAPI extends require$$0$1.EventEmitter {
                 }
                 else if (message.T === "error") {
                     log$l(`${streamType} stream error: ${message.msg} (code: ${message.code}, raw: ${JSON.stringify(message)})`, { type: "error" });
+                    // Alpaca code 406: "connection limit exceeded" — account-wide
+                    // concurrent-WS cap reached. The Alpaca server will close the
+                    // socket immediately after this frame, which would normally
+                    // trigger our standard sub-second exponential reconnect chain
+                    // (1 s, 2 s, 4 s, 8 s, 16 s, 30 s × 5) — exactly the wrong
+                    // behaviour against a rate-limit response. Stamp the recency
+                    // marker so {@link scheduleReconnect} switches to the
+                    // 5-minute jittered backoff instead.
+                    if (typeof message.code === "number" &&
+                        message.code === 406) {
+                        this.lastConnectionLimitAt[streamType] = Date.now();
+                    }
                 }
                 else if (message.S) {
                     super.emit(`${streamType}-${message.T}`, message);
@@ -2855,6 +2909,37 @@ class AlpacaMarketDataAPI extends require$$0$1.EventEmitter {
         });
     }
     scheduleReconnect(streamType) {
+        // 406-recovery fast path. When the most recent close was preceded
+        // by an Alpaca app-level 406 ("connection limit exceeded"), the
+        // standard sub-second exponential ramp is exactly wrong — it
+        // hammers the rate-limit endpoint and prolongs the slot pressure.
+        // Use a 5-minute jittered backoff instead and reset the normal
+        // attempt counter so we don't fall off the end of maxAttempts
+        // and permanently give up on a transient rollover blip.
+        const connectionLimitAt = this.lastConnectionLimitAt[streamType];
+        const isRecentConnectionLimit = typeof connectionLimitAt === "number" &&
+            Date.now() - connectionLimitAt <= this.CONNECTION_LIMIT_RECENCY_MS;
+        if (isRecentConnectionLimit) {
+            const jitter = Math.floor((Math.random() - 0.5) *
+                2 *
+                this.CONNECTION_LIMIT_BACKOFF_JITTER_MS);
+            const delayMs = this.CONNECTION_LIMIT_BACKOFF_MS + jitter;
+            // Reset normal attempt counter so the next 406 retry doesn't
+            // inherit a stale exponential cap.
+            this.reconnectAttempts[streamType] = 0;
+            // Consume the recency marker — subsequent reconnects fall back
+            // to the standard exponential path unless a new 406 arrives.
+            delete this.lastConnectionLimitAt[streamType];
+            log$l(`${streamType} stream: Alpaca 406 connection-limit recovery — backing off ${Math.round(delayMs / 1000)}s before retry to allow account-wide slot release`, { type: "warn" });
+            if (this.reconnectTimers[streamType]) {
+                clearTimeout(this.reconnectTimers[streamType]);
+            }
+            this.reconnectTimers[streamType] = setTimeout(() => {
+                log$l(`${streamType} stream: attempting reconnect after 406-recovery backoff`, { type: "info" });
+                this.connect(streamType);
+            }, delayMs);
+            return;
+        }
         const attempts = this.reconnectAttempts[streamType] ?? 0;
         const maxAttempts = 10;
         if (attempts >= maxAttempts) {
@@ -11532,7 +11617,6 @@ function calculateBollingerBands(priceData, { period = 20, standardDeviations =
             close: priceData[i].close,
         });
     }
-    // logIfDebug(`Calculated Bollinger Bands for ${result.length} periods`);
     return result;
 }
 /**
@@ -11595,7 +11679,6 @@ function calculateEMA(priceData, { period = 20, period2 = 9 } = {}) {
         }
         result.push(entry);
     }
-    // logIfDebug(`Calculated EMA for ${result.length} periods`);
     return result;
 }
 /**
@@ -11657,7 +11740,6 @@ function calculateFibonacciLevels(priceData, { lookbackPeriod = 20, retracementL
             close: priceData[i].close,
         });
     }
-    // logIfDebug(`Calculated Fibonacci levels for ${result.length} periods`);
     return result;
 }
 /**
@@ -11705,7 +11787,6 @@ function calculateMACD(priceData, { shortPeriod = 12, longPeriod = 26, signalPer
             close: emaLong[i].close,
         });
     }
-    // logIfDebug(`Calculated MACD for ${result.length} periods`);
     return result;
 }
 /**
@@ -11761,7 +11842,6 @@ function calculateRSI(priceData, { period = 14 } = {}) {
             close: priceData[i].close,
         });
     }
-    // logIfDebug(`Calculated RSI for ${result.length} periods`);
     return result;
 }
 /**
@@ -11814,7 +11894,6 @@ function calculateStochasticOscillator(priceData, { lookbackPeriod = 5, signalPe
             });
         }
     }
-    // logIfDebug(`Calculated Stochastic Oscillator for ${result.length} periods`);
     return result;
 }
 /**