@adaptic/utils 0.1.44 → 0.1.45

package/dist/types/utils/http-keep-alive.d.ts

@@ -1,110 +0,0 @@
-/**
- * HTTP connection pooling and keep-alive configuration.
- *
- * Node.js (>=20) uses undici as its built-in fetch implementation, which
- * automatically maintains an internal connection pool with keep-alive enabled
- * by default. This module provides:
- *
- * 1. Explicit documentation of the connection pooling behavior
- * 2. A configured HTTP Agent for use with node:http/node:https if needed
- * 3. Verification utilities to confirm keep-alive is active
- *
- * ## Connection Pooling Behavior
- *
- * **Native fetch (undici):** The global `fetch()` used throughout this package
- * uses Node.js built-in undici which maintains persistent connections by default.
- * Connections are kept alive and reused across requests to the same origin.
- * No additional configuration is needed for fetch-based API calls.
- *
- * **Alpaca SDK (@alpacahq/alpaca-trade-api):** The SDK uses its own internal
- * HTTP client with connection reuse. The SDK is configured through `AlpacaClient`
- * in `src/alpaca/client.ts` via the `createAlpacaClient()` factory which caches
- * client instances by API key + account type.
- *
- * **WebSocket connections:** Trading API and market data WebSocket connections
- * are long-lived persistent connections managed by `AlpacaTradingAPI` and
- * `AlpacaMarketDataAPI` respectively.
- *
- * ## API Client Summary
- *
- * | API Client | Transport | Keep-Alive | Connection Reuse |
- * |------------|-----------|------------|------------------|
- * | Alpaca Trading (direct) | fetch() | Built-in | Undici pool |
- * | Alpaca Market Data | fetch() | Built-in | Undici pool |
- * | Alpaca SDK | internal | Built-in | SDK managed |
- * | Polygon.io | fetch() via fetchWithRetry | Built-in | Undici pool |
- * | Alpha Vantage | fetch() | Built-in | Undici pool |
- * | WebSocket (Trading) | ws | Persistent | Long-lived |
- * | WebSocket (Market Data) | ws | Persistent | Long-lived |
- */
-import http from "http";
-import https from "https";
-/**
- * Default keep-alive configuration values.
- * These are applied when creating explicit HTTP agents for non-fetch use cases.
- */
-export declare const KEEP_ALIVE_DEFAULTS: {
-    /** Enable keep-alive connections */
-    readonly keepAlive: true;
-    /** Initial delay before sending keep-alive probes (in milliseconds) */
-    readonly keepAliveMsecs: 60000;
-    /** Maximum number of sockets per host */
-    readonly maxSockets: 50;
-    /** Maximum total number of sockets */
-    readonly maxTotalSockets: 256;
-    /** Maximum number of free (idle) sockets per host */
-    readonly maxFreeSockets: 10;
-    /** Socket timeout for idle connections (in milliseconds) */
-    readonly timeout: 60000;
-};
-/**
- * Pre-configured HTTP agent with keep-alive enabled.
- * Use this when making requests through node:http (not needed for fetch).
- */
-export declare const httpAgent: http.Agent;
-/**
- * Pre-configured HTTPS agent with keep-alive enabled.
- * Use this when making requests through node:https (not needed for fetch).
- */
-export declare const httpsAgent: https.Agent;
-/**
- * Connection pool status information
- */
-export interface ConnectionPoolStatus {
-    /** Name of the HTTP agent */
-    name: string;
-    /** Whether keep-alive is enabled */
-    keepAlive: boolean;
-    /** Number of active sockets */
-    activeSockets: number;
-    /** Number of free (idle) sockets */
-    freeSockets: number;
-    /** Number of pending requests (waiting for a socket) */
-    pendingRequests: number;
-    /** Maximum sockets per host */
-    maxSockets: number;
-    /** Maximum free sockets per host */
-    maxFreeSockets: number;
-}
-/**
- * Get the connection pool status for an HTTP/HTTPS agent.
- * Useful for monitoring and debugging connection reuse.
- *
- * @param agent - The HTTP/HTTPS agent to inspect
- * @param name - A human-readable name for the agent
- * @returns Connection pool status information
- */
-export declare function getAgentPoolStatus(agent: http.Agent | https.Agent, name?: string): ConnectionPoolStatus;
-/**
- * Verifies that keep-alive is properly configured for the Node.js built-in fetch.
- * Node.js >= 20 uses undici internally, which has keep-alive enabled by default.
- *
- * @returns Object indicating whether keep-alive is expected to be active
- */
-export declare function verifyFetchKeepAlive(): {
-    supported: boolean;
-    nodeVersion: string;
-    undiciBuiltIn: boolean;
-    keepAliveExpected: boolean;
-};
-//# sourceMappingURL=http-keep-alive.d.ts.map

package/dist/types/utils/http-keep-alive.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"http-keep-alive.d.ts","sourceRoot":"","sources":["../../../src/utils/http-keep-alive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B;;;GAGG;AACH,eAAO,MAAM,mBAAmB;IAC9B,oCAAoC;;IAEpC,uEAAuE;;IAEvE,yCAAyC;;IAEzC,sCAAsC;;IAEtC,qDAAqD;;IAErD,4DAA4D;;CAEpD,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,SAAS,YAOpB,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,UAAU,aAOrB,CAAC;AAEH;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,SAAS,EAAE,OAAO,CAAC;IACnB,+BAA+B;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,oCAAoC;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,eAAe,EAAE,MAAM,CAAC;IACxB,+BAA+B;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,oCAAoC;IACpC,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,EAC/B,IAAI,GAAE,MAAkB,GACvB,oBAAoB,CA4BtB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI;IACtC,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,OAAO,CAAC;IACvB,iBAAiB,EAAE,OAAO,CAAC;CAC5B,CAeA"}

package/dist/types/utils/paginator.d.ts

@@ -1,154 +0,0 @@
-/**
- * Configuration for cursor-based pagination.
- * Used by Alpaca APIs that return `next_page_token`.
- */
-export interface CursorPaginationConfig<TItem, TResponse> {
-    /** Pagination strategy type */
-    type: "cursor";
-    /**
-     * Function that fetches a single page of results.
-     * @param cursor - The cursor/page token for the next page (undefined for first page)
-     * @returns The API response for that page
-     */
-    fetchPage: (cursor: string | undefined) => Promise<TResponse>;
-    /**
-     * Function that extracts items from the API response.
-     * @param response - The raw API response
-     * @returns Array of items from this page
-     */
-    getItems: (response: TResponse) => TItem[];
-    /**
-     * Function that extracts the next cursor/page token from the response.
-     * Returns undefined/null/empty string when there are no more pages.
-     * @param response - The raw API response
-     * @returns The next page token, or a falsy value if no more pages
-     */
-    getNextCursor: (response: TResponse) => string | undefined | null;
-    /** Maximum number of items to collect (optional; defaults to no limit) */
-    maxItems?: number;
-    /** Maximum number of pages to fetch (safety limit; defaults to 1000) */
-    maxPages?: number;
-    /** Label for logging purposes */
-    label?: string;
-}
-/**
- * Configuration for URL-based pagination.
- * Used by Polygon APIs that return `next_url`.
- */
-export interface UrlPaginationConfig<TItem, TResponse> {
-    /** Pagination strategy type */
-    type: "url";
-    /**
-     * Function that fetches a page from a given URL.
-     * For the first page, the URL is the initial request URL.
-     * For subsequent pages, the URL comes from the previous response.
-     * @param url - The URL to fetch
-     * @returns The API response for that page
-     */
-    fetchPage: (url: string) => Promise<TResponse>;
-    /** The initial URL for the first page */
-    initialUrl: string;
-    /**
-     * Function that extracts items from the API response.
-     * @param response - The raw API response
-     * @returns Array of items from this page
-     */
-    getItems: (response: TResponse) => TItem[];
-    /**
-     * Function that extracts the next URL from the response.
-     * Returns undefined/null/empty string when there are no more pages.
-     * @param response - The raw API response
-     * @returns The next page URL, or a falsy value if no more pages
-     */
-    getNextUrl: (response: TResponse) => string | undefined | null;
-    /** Maximum number of items to collect (optional; defaults to no limit) */
-    maxItems?: number;
-    /** Maximum number of pages to fetch (safety limit; defaults to 1000) */
-    maxPages?: number;
-    /** Label for logging purposes */
-    label?: string;
-}
-/**
- * Configuration for offset-based pagination.
- * Used by APIs that accept page/offset parameters.
- */
-export interface OffsetPaginationConfig<TItem, TResponse> {
-    /** Pagination strategy type */
-    type: "offset";
-    /**
-     * Function that fetches a page at a given offset.
-     * @param offset - The current offset (starts at 0)
-     * @param limit - The page size
-     * @returns The API response for that page
-     */
-    fetchPage: (offset: number, limit: number) => Promise<TResponse>;
-    /**
-     * Function that extracts items from the API response.
-     * @param response - The raw API response
-     * @returns Array of items from this page
-     */
-    getItems: (response: TResponse) => TItem[];
-    /** Number of items per page */
-    pageSize: number;
-    /**
-     * Optional function to determine the total number of items.
-     * If not provided, pagination stops when a page returns fewer items than pageSize.
-     * @param response - The first API response
-     * @returns Total number of items available
-     */
-    getTotalCount?: (response: TResponse) => number;
-    /** Maximum number of items to collect (optional; defaults to no limit) */
-    maxItems?: number;
-    /** Maximum number of pages to fetch (safety limit; defaults to 1000) */
-    maxPages?: number;
-    /** Label for logging purposes */
-    label?: string;
-}
-/** Union type of all pagination configurations */
-export type PaginationConfig<TItem, TResponse> = CursorPaginationConfig<TItem, TResponse> | UrlPaginationConfig<TItem, TResponse> | OffsetPaginationConfig<TItem, TResponse>;
-/**
- * Creates an async iterator that paginates through API results.
- * Yields individual items one at a time across all pages.
- *
- * @param config - Pagination configuration
- * @returns AsyncGenerator that yields items one at a time
- *
- * @example
- * ```typescript
- * // Cursor-based (Alpaca)
- * const iterator = paginate({
- *   type: 'cursor',
- *   fetchPage: (cursor) => alpacaAPI.getOrders({ page_token: cursor }),
- *   getItems: (response) => response.orders,
- *   getNextCursor: (response) => response.next_page_token,
- *   label: 'getOrders',
- * });
- *
- * for await (const order of iterator) {
- *   processOrder(order);
- * }
- * ```
- */
-export declare function paginate<TItem, TResponse>(config: PaginationConfig<TItem, TResponse>): AsyncGenerator<TItem, void, undefined>;
-/**
- * Collects all items from a paginated API into a single array.
- * This is a convenience wrapper around `paginate()`.
- *
- * @param config - Pagination configuration
- * @returns Array of all items collected across all pages
- *
- * @example
- * ```typescript
- * // Collect all orders
- * const allOrders = await paginateAll({
- *   type: 'cursor',
- *   fetchPage: (cursor) => alpacaAPI.getOrders({ page_token: cursor, limit: 100 }),
- *   getItems: (response) => response,
- *   getNextCursor: (response) => response.next_page_token,
- *   maxItems: 500,
- *   label: 'getAllOrders',
- * });
- * ```
- */
-export declare function paginateAll<TItem, TResponse>(config: PaginationConfig<TItem, TResponse>): Promise<TItem[]>;
-//# sourceMappingURL=paginator.d.ts.map

package/dist/types/utils/paginator.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"paginator.d.ts","sourceRoot":"","sources":["../../../src/utils/paginator.ts"],"names":[],"mappings":"AAYA;;;GAGG;AACH,MAAM,WAAW,sBAAsB,CAAC,KAAK,EAAE,SAAS;IACtD,+BAA+B;IAC/B,IAAI,EAAE,QAAQ,CAAC;IACf;;;;OAIG;IACH,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IAC9D;;;;OAIG;IACH,QAAQ,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,KAAK,EAAE,CAAC;IAC3C;;;;;OAKG;IACH,aAAa,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC;IAClE,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB,CAAC,KAAK,EAAE,SAAS;IACnD,+BAA+B;IAC/B,IAAI,EAAE,KAAK,CAAC;IACZ;;;;;;OAMG;IACH,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IAC/C,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,QAAQ,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,KAAK,EAAE,CAAC;IAC3C;;;;;OAKG;IACH,UAAU,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC;IAC/D,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB,CAAC,KAAK,EAAE,SAAS;IACtD,+BAA+B;IAC/B,IAAI,EAAE,QAAQ,CAAC;IACf;;;;;OAKG;IACH,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACjE;;;;OAIG;IACH,QAAQ,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,KAAK,EAAE,CAAC;IAC3C,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,MAAM,CAAC;IAChD,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,kDAAkD;AAClD,MAAM,MAAM,gBAAgB,CAAC,KAAK,EAAE,SAAS,IACzC,sBAAsB,CAAC,KAAK,EAAE,SAAS,CAAC,GACxC,mBAAmB,CAAC,KAAK,EAAE,SAAS,CAAC,GACrC,sBAAsB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;AAK7C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAuB,QAAQ,CAAC,KAAK,EAAE,SAAS,EAC9C,MAAM,EAAE,gBAAgB,CAAC,KAAK,EAAE,SAAS,CAAC,GACzC,cAAc,CAAC,KAAK,EAAE,IAAI,EAAE,SAAS,CAAC,CA8FxC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,SAAS,EAChD,MAAM,EAAE,gBAAgB,CAAC,KAAK,EAAE,SAAS,CAAC,GACzC,OAAO,CAAC,KAAK,EAAE,CAAC,CAQlB"}

package/dist/types/utils/retry.d.ts

@@ -1,78 +0,0 @@
-/**
- * Retry utility with exponential backoff for handling transient errors in external API calls.
- *
- * Features:
- * - Configurable retry attempts and delays
- * - Exponential backoff with jitter to prevent thundering herd
- * - Respects Retry-After headers for rate limiting (429)
- * - Fail-fast for non-retryable errors (4xx client errors)
- * - Detailed error logging with context
- */
-export interface RetryConfig {
-    /** Maximum number of retry attempts (default: 3) */
-    maxRetries: number;
-    /** Initial delay in milliseconds before first retry (default: 1000) */
-    baseDelayMs: number;
-    /** Maximum delay in milliseconds between retries (default: 30000) */
-    maxDelayMs: number;
-    /** HTTP status codes that should trigger a retry (default: [429, 500, 502, 503, 504]) */
-    retryableStatusCodes: number[];
-    /** Whether to retry on network errors (default: true) */
-    retryOnNetworkError: boolean;
-    /** Optional callback invoked on each retry attempt */
-    onRetry?: (attempt: number, error: unknown) => void;
-}
-/**
- * Wraps an async function with retry logic and exponential backoff.
- *
- * This utility handles transient errors in external API calls by automatically retrying
- * failed requests with intelligent backoff strategies. It respects rate limit headers,
- * fails fast on non-retryable errors, and provides detailed logging.
- *
- * @template T - The return type of the wrapped function
- * @param fn - The async function to wrap with retry logic
- * @param config - Retry configuration (merged with defaults)
- * @param label - A descriptive label for logging (e.g., 'Polygon.fetchTickerInfo')
- * @returns A promise that resolves to the function's return value
- * @throws The last error encountered if all retries are exhausted
- *
- * @example
- * ```typescript
- * // Basic usage with defaults
- * const data = await withRetry(
- *   async () => fetch('https://api.example.com/data'),
- *   {},
- *   'ExampleAPI.fetchData'
- * );
- *
- * // Custom configuration for rate-limited API
- * const result = await withRetry(
- *   async () => alphaVantageAPI.getQuote(symbol),
- *   {
- *     maxRetries: 5,
- *     baseDelayMs: 5000,
- *     maxDelayMs: 60000,
- *     onRetry: (attempt, error) => {
- *       getLogger().info(`Retry ${attempt} after error:`, error);
- *     }
- *   },
- *   'AlphaVantage.getQuote'
- * );
- * ```
- */
-export declare function withRetry<T>(fn: () => Promise<T>, config?: Partial<RetryConfig>, label?: string): Promise<T>;
-/**
- * API-specific retry configurations for different external services.
- * These configurations are tuned based on each API's rate limits and characteristics.
- */
-export declare const API_RETRY_CONFIGS: {
-    /** Polygon.io API - 5 requests/second rate limit */
-    POLYGON: Partial<RetryConfig>;
-    /** Alpha Vantage API - 5 requests/minute rate limit (more strict) */
-    ALPHA_VANTAGE: Partial<RetryConfig>;
-    /** Alpaca API - generally reliable, shorter retry window */
-    ALPACA: Partial<RetryConfig>;
-    /** Generic crypto API configuration */
-    CRYPTO: Partial<RetryConfig>;
-};
-//# sourceMappingURL=retry.d.ts.map

package/dist/types/utils/retry.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../../src/utils/retry.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC;IACnB,yFAAyF;IACzF,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,yDAAyD;IACzD,mBAAmB,EAAE,OAAO,CAAC;IAC7B,sDAAsD;IACtD,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACrD;AA4LD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,MAAM,GAAE,OAAO,CAAC,WAAW,CAAM,EACjC,KAAK,GAAE,MAAkB,GACxB,OAAO,CAAC,CAAC,CAAC,CAmGZ;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB;IAC5B,oDAAoD;aAO/C,OAAO,CAAC,WAAW,CAAC;IAEzB,qEAAqE;mBAOhE,OAAO,CAAC,WAAW,CAAC;IAEzB,4DAA4D;YAOvD,OAAO,CAAC,WAAW,CAAC;IAEzB,uCAAuC;YAOlC,OAAO,CAAC,WAAW,CAAC;CAC1B,CAAC"}