@adaptic/utils 0.0.965 → 0.0.966

package/dist/test.js

@@ -640,6 +640,67 @@ class DisplayManager {
     }
 }
 
+/**
+ * Configurable logger interface compatible with Pino and other logging libraries.
+ * Provides structured logging with context support.
+ */
+/**
+ * Normalizes context to a format suitable for logging.
+ * Handles various types including primitives, objects, and errors.
+ */
+function normalizeContext(context) {
+    if (context === undefined || context === null) {
+        return undefined;
+    }
+    if (typeof context === "object" && context !== null) {
+        // Handle Error objects
+        if (context instanceof Error) {
+            return {
+                error: {
+                    message: context.message,
+                    name: context.name,
+                    stack: context.stack,
+                },
+            };
+        }
+        // Already an object, return as-is
+        return context;
+    }
+    // Primitive types - wrap in object
+    return { value: context };
+}
+/**
+ * Default logger implementation that uses console for backward compatibility.
+ * Formats messages in a simple readable format.
+ */
+const defaultLogger = {
+    error: (msg, ctx) => console.error(msg, normalizeContext(ctx) || ""),
+    warn: (msg, ctx) => console.warn(msg, normalizeContext(ctx) || ""),
+    info: (msg, ctx) => console.info(msg, normalizeContext(ctx) || ""),
+    debug: (msg, ctx) => console.debug(msg, normalizeContext(ctx) || ""),
+};
+let currentLogger = defaultLogger;
+/**
+ * Gets the current logger instance.
+ * Use this to log messages throughout the application.
+ *
+ * @returns The current logger instance
+ *
+ * @example
+ * ```typescript
+ * import { getLogger } from '@adaptic/utils';
+ *
+ * const logger = getLogger();
+ * logger.error('Operation failed', { userId: 123, operation: 'createOrder' });
+ * logger.warn('Rate limit approaching', { remaining: 10 });
+ * logger.info('Order created', { orderId: 'abc123', symbol: 'AAPL' });
+ * logger.debug('Cache hit', { key: 'user:123' });
+ * ```
+ */
+function getLogger() {
+    return currentLogger;
+}
+
 /**
  * Logs a message.
  *
@@ -1482,6 +1543,311 @@ function createTimeoutSignal(ms) {
     return AbortSignal.timeout(ms);
 }
 
+/**
+ * Structured error type hierarchy for all API integrations
+ *
+ * This module provides a comprehensive error handling system for external API integrations,
+ * including Alpaca, Massive, and AlphaVantage services.
+ */
+/**
+ * Base error class for all @adaptic/utils errors
+ * Extends Error with additional context about service, error code, and retry capability
+ */
+class AdapticUtilsError extends Error {
+    code;
+    service;
+    isRetryable;
+    cause;
+    name;
+    constructor(message, code, service, isRetryable = false, cause) {
+        super(message);
+        this.code = code;
+        this.service = service;
+        this.isRetryable = isRetryable;
+        this.cause = cause;
+        this.name = this.constructor.name;
+        // Maintains proper stack trace for where error was thrown (only available on V8)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+}
+/**
+ * Rate limit errors (429)
+ * Used when API rate limits are exceeded
+ * Always retryable, often with retry-after header information
+ */
+class RateLimitError extends AdapticUtilsError {
+    service;
+    retryAfterMs;
+    constructor(message, service, retryAfterMs, cause) {
+        super(message, "RATE_LIMIT", service, true, // Rate limit errors are always retryable
+        cause);
+        this.service = service;
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+
+/**
+ * Token bucket rate limiter for external API integrations
+ *
+ * Implements client-side rate limiting to prevent exceeding API quotas
+ * and ensure fair usage of external services like Alpaca, Massive, and AlphaVantage.
+ *
+ * @example
+ * ```typescript
+ * import { rateLimiters } from '@adaptic/utils';
+ *
+ * // Before making an API call
+ * await rateLimiters.alpaca.acquire();
+ * const result = await makeAlpacaApiCall();
+ * ```
+ */
+/**
+ * Token bucket rate limiter implementation
+ *
+ * Uses the token bucket algorithm to control the rate of API requests.
+ * Tokens are consumed on each request and refilled at a constant rate.
+ * Requests that exceed the available tokens are queued and processed
+ * when tokens become available.
+ */
+class TokenBucketRateLimiter {
+    config;
+    tokens;
+    lastRefill;
+    queue = [];
+    timeoutMs;
+    processingQueue = false;
+    /**
+     * Creates a new rate limiter instance
+     *
+     * @param config - Rate limiter configuration
+     *
+     * @example
+     * ```typescript
+     * // Alpaca: 200 requests per minute
+     * const alpacaLimiter = new TokenBucketRateLimiter({
+     *   maxTokens: 200,
+     *   refillRate: 200 / 60, // ~3.33 per second
+     *   label: 'alpaca',
+     *   timeoutMs: 60000
+     * });
+     * ```
+     */
+    constructor(config) {
+        this.config = config;
+        this.tokens = config.maxTokens;
+        this.lastRefill = Date.now();
+        this.timeoutMs = config.timeoutMs ?? 60000; // Default 60 second timeout
+    }
+    /**
+     * Acquires a token for making an API request
+     *
+     * If a token is available, it is consumed immediately.
+     * If no tokens are available, the request is queued and will resolve
+     * when a token becomes available or reject if it times out.
+     *
+     * @throws {RateLimitError} If the request times out waiting for a token
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await limiter.acquire();
+     *   // Make API call
+     * } catch (error) {
+     *   if (error instanceof RateLimitError) {
+     *     // Handle rate limit timeout
+     *   }
+     * }
+     * ```
+     */
+    async acquire() {
+        const logger = getLogger();
+        this.refill();
+        if (this.tokens > 0) {
+            this.tokens--;
+            logger.debug(`Rate limit token acquired for ${this.config.label}`, {
+                remainingTokens: this.tokens,
+                queueLength: this.queue.length,
+            });
+            return;
+        }
+        // No tokens available, queue the request
+        logger.debug(`Rate limit reached for ${this.config.label}, queuing request`, {
+            queueLength: this.queue.length,
+        });
+        return new Promise((resolve, reject) => {
+            const timeoutHandle = setTimeout(() => {
+                // Remove from queue on timeout
+                const index = this.queue.findIndex((req) => req.timeoutHandle === timeoutHandle);
+                if (index !== -1) {
+                    this.queue.splice(index, 1);
+                }
+                const error = new RateLimitError(`Rate limit timeout for ${this.config.label} after ${this.timeoutMs}ms`, this.config.label, undefined);
+                logger.warn(`Rate limit timeout for ${this.config.label}`, {
+                    queueLength: this.queue.length,
+                    timeoutMs: this.timeoutMs,
+                });
+                reject(error);
+            }, this.timeoutMs);
+            this.queue.push({ resolve, reject, timeoutHandle });
+        });
+    }
+    /**
+     * Refills tokens based on elapsed time and processes queued requests
+     *
+     * Tokens are refilled at the configured rate up to the maximum capacity.
+     * If tokens are available after refilling, queued requests are processed.
+     */
+    refill() {
+        const now = Date.now();
+        const elapsed = (now - this.lastRefill) / 1000; // Convert to seconds
+        const tokensToAdd = elapsed * this.config.refillRate;
+        this.tokens = Math.min(this.config.maxTokens, this.tokens + tokensToAdd);
+        this.lastRefill = now;
+        // Process queued requests if we have tokens
+        this.processQueue();
+    }
+    /**
+     * Processes queued requests when tokens are available
+     *
+     * Prevents concurrent queue processing to ensure FIFO order.
+     */
+    processQueue() {
+        // Prevent concurrent queue processing
+        if (this.processingQueue) {
+            return;
+        }
+        this.processingQueue = true;
+        const logger = getLogger();
+        try {
+            while (this.queue.length > 0 && this.tokens > 0) {
+                this.tokens--;
+                const next = this.queue.shift();
+                if (next) {
+                    clearTimeout(next.timeoutHandle);
+                    next.resolve();
+                    logger.debug(`Processed queued request for ${this.config.label}`, {
+                        remainingTokens: this.tokens,
+                        remainingQueue: this.queue.length,
+                    });
+                }
+            }
+        }
+        finally {
+            this.processingQueue = false;
+        }
+    }
+    /**
+     * Gets the current number of available tokens
+     *
+     * @returns Number of tokens currently available
+     */
+    getAvailableTokens() {
+        this.refill();
+        return Math.floor(this.tokens);
+    }
+    /**
+     * Gets the current queue length
+     *
+     * @returns Number of requests waiting for tokens
+     */
+    getQueueLength() {
+        return this.queue.length;
+    }
+    /**
+     * Clears all queued requests and resets the token bucket
+     *
+     * All queued requests will be rejected with a RateLimitError.
+     * Useful for cleanup or when changing rate limit configurations.
+     */
+    reset() {
+        const logger = getLogger();
+        // Reject all queued requests
+        for (const request of this.queue) {
+            clearTimeout(request.timeoutHandle);
+            request.reject(new RateLimitError(`Rate limiter reset for ${this.config.label}`, this.config.label, undefined));
+        }
+        this.queue = [];
+        this.tokens = this.config.maxTokens;
+        this.lastRefill = Date.now();
+        this.processingQueue = false;
+        logger.info(`Rate limiter reset for ${this.config.label}`, {
+            maxTokens: this.config.maxTokens,
+        });
+    }
+}
+/**
+ * Pre-configured rate limiters for common external APIs
+ *
+ * These limiters are configured based on the documented rate limits
+ * for each service. Adjust the configurations if you have different
+ * tier access or if limits change.
+ *
+ * @example
+ * ```typescript
+ * import { rateLimiters } from '@adaptic/utils';
+ *
+ * // Use before making API calls
+ * await rateLimiters.alpaca.acquire();
+ * await rateLimiters.massive.acquire();
+ * await rateLimiters.alphaVantage.acquire();
+ * ```
+ */
+const rateLimiters = {
+    /**
+     * Alpaca API rate limiter
+     *
+     * Configured for 1000 requests per minute (paid tier).
+     * The token bucket allows burst up to maxTokens, then refills at the steady rate.
+     * See: https://alpaca.markets/docs/api-references/trading-api/#rate-limit
+     */
+    alpaca: new TokenBucketRateLimiter({
+        maxTokens: 1000,
+        refillRate: 1000 / 60, // 1000 requests per 60 seconds (~16.67/sec)
+        label: "alpaca",
+        timeoutMs: 60000,
+    }),
+    /**
+     * Massive.com API rate limiter
+     *
+     * Configured generously for paid unlimited tier. The bucket exists only as a
+     * safety net against runaway loops — the 1000 token burst and 500/sec refill
+     * should never be hit under normal operation. If the paid plan truly has no
+     * hard limit, this just prevents accidental self-DDoS.
+     */
+    massive: new TokenBucketRateLimiter({
+        maxTokens: 1000,
+        refillRate: 500, // 500 tokens/sec refill — effectively unlimited for paid tier
+        label: "massive",
+        timeoutMs: 30000,
+    }),
+    /**
+     * AlphaVantage API rate limiter
+     *
+     * Configured for 5 requests per minute (free tier).
+     * For premium tier (75/min), create a custom limiter:
+     *
+     * @example
+     * ```typescript
+     * const premiumAV = new TokenBucketRateLimiter({
+     *   maxTokens: 75,
+     *   refillRate: 75 / 60,
+     *   label: 'alphaVantage-premium',
+     *   timeoutMs: 60000,
+     * });
+     * ```
+     *
+     * See: https://www.alphavantage.co/premium/
+     */
+    alphaVantage: new TokenBucketRateLimiter({
+        maxTokens: 5,
+        refillRate: 5 / 60, // 5 requests per 60 seconds (~0.083/sec)
+        label: "alphaVantage",
+        timeoutMs: 60000,
+    }),
+};
+
 const log$1 = (message, options = { type: "info" }) => {
     log$2(message, { ...options, source: "AlpacaMarketDataAPI" });
 };
@@ -1888,6 +2254,11 @@ class AlpacaMarketDataAPI extends EventEmitter {
                     }
                 });
             }
+            // Gate all Alpaca market-data calls through the shared 1000/min token
+            // bucket so concurrent callers (bar fetches, quotes, options, snapshots)
+            // can't overrun Alpaca's server-side rate limit. Prior to this, parallel
+            // historical-bar fan-out produced ~125 server-side 429s per minute.
+            await rateLimiters.alpaca.acquire();
             const response = await fetch(url.toString(), {
                 method,
                 headers: this.headers,