@adaptic/utils 0.0.99

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

@@ -0,0 +1,154 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,78 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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"}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@adaptic/utils",
+  "version": "0.0.99",
+  "author": "Adaptic.ai",
+  "description": "Utility functions used in Adaptic app and Lambda functions",
+  "always-build-npm": true,
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/types/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "types": "./dist/types/index.d.ts"
+    }
+  },
+  "publishConfig": {
+    "tag": "stable"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && rollup -c",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:legacy": "npm run build && node dist/test.js",
+    "build:analyze": "ANALYZE_BUNDLE=true npm run build",
+    "docs": "typedoc",
+    "docs:watch": "typedoc --watch",
+    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s"
+  },
+  "dependencies": {
+    "@adaptic/backend-legacy": "^0.0.59",
+    "@adaptic/lumic-utils": "^1.0.6",
+    "@alpacahq/alpaca-trade-api": "^3.1.3",
+    "@apollo/client": "^3.13.8",
+    "chalk": "^5.4.1",
+    "date-fns": "^4.1.0",
+    "date-fns-tz": "^3.2.0",
+    "lru-cache": "^11.2.2",
+    "ms": "^2.1.3",
+    "p-limit": "^6.2.0",
+    "zod": "^3.25.76"
+  },
+  "peerDependencies": {
+    "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+  },
+  "license": "ISC",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^28.0.6",
+    "@rollup/plugin-json": "^6.1.0",
+    "@rollup/plugin-node-resolve": "^16.0.1",
+    "@rollup/plugin-typescript": "^12.1.4",
+    "@types/date-fns": "^2.6.3",
+    "@types/ms": "^2.1.0",
+    "@types/ws": "^8.18.1",
+    "@vitest/coverage-v8": "^4.0.18",
+    "conventional-changelog-cli": "^5.0.0",
+    "fast-check": "^4.5.3",
+    "lightweight-charts": "^5.0.8",
+    "react": "^19.1.0",
+    "rollup": "^4.46.2",
+    "rollup-cli": "^1.0.9",
+    "rollup-plugin-visualizer": "^6.0.5",
+    "typedoc": "^0.28.16",
+    "typescript": "^5.8.3",
+    "vitest": "^4.0.18"
+  }
+}