@provex/utils 1.9.2-rc.20260721051954.c2db778 → 1.9.2-rc.20260722211737.69a2b06

package/dist/transports.d.ts

@@ -27,6 +27,40 @@ import { type ChainId } from './chain.js';
  *   and g4mm4 does not operate a Base RPC.
  */
 export declare const FALLBACK_RPC_URLS: Partial<Record<ChainId, readonly string[]>>;
+/**
+ * Parse a comma-separated RPC URL list into an ordered array of valid URLs.
+ *
+ * This is the single parser for every comma-separated RPC env in the repo —
+ * the browser's `VITE_RPC_URLS_<chainId>` and the server's `BASE_RPC_URL` /
+ * `PULSECHAIN_RPC_URL` all share this shape, matching the `PONDER_RPC_URL_*`
+ * convention the indexer already uses.
+ *
+ * @param raw - Raw env value. Missing, blank, and all-invalid inputs yield `[]`
+ * so callers can treat the result as a priority-ordered prefix without
+ * null-checking.
+ * @returns Ordered array of trimmed, validated URL strings.
+ *
+ * @example
+ * ```ts
+ * parseRpcUrlList('https://a.example, https://b.example')
+ * // ['https://a.example', 'https://b.example']
+ * ```
+ */
+export declare const parseRpcUrlList: (raw: string | undefined | null) => string[];
+/**
+ * How {@link createChainTransport} distributes traffic across the resolved
+ * URL list.
+ *
+ * - `ranked` — viem's latency-based load balancing. The fastest healthy
+ *   endpoint serves traffic. Correct for browsers, where the goal is the
+ *   snappiest response and every endpoint is equally cheap.
+ * - `ordered` — strict priority. Entry #1 serves every request and later
+ *   entries are touched only when the ones before them error. Correct when
+ *   later entries are metered (a paid provider held in reserve), because
+ *   ranking would otherwise route traffic *to* the fast paid endpoint and
+ *   defeat the reason it was placed second.
+ */
+export type ChainTransportStrategy = 'ranked' | 'ordered';
 /**
  * Options accepted by {@link createChainTransport}.
  */
@@ -36,6 +70,11 @@ interface CreateChainTransportOptions {
      * and the chain default. Typically parsed from a `VITE_RPC_URLS_*` env.
      */
     userUrls?: readonly string[];
+    /**
+     * Traffic-distribution strategy. Defaults to `ranked`, preserving the
+     * latency-optimised behaviour every browser call-site relies on.
+     */
+    strategy?: ChainTransportStrategy;
 }
 /**
  * Resolve the ordered RPC URL list for a chain: caller overrides, then the
@@ -45,11 +84,17 @@ interface CreateChainTransportOptions {
  * @param chainId - The chain ID to resolve URLs for. Must resolve via
  * {@link chainIdToChain}.
  * @param options - Optional caller-supplied overrides.
- * @returns Priority-ordered list of valid RPC URLs (always non-empty,
- * because the chain default is always present).
+ * @returns Priority-ordered, de-duplicated list of valid RPC URLs (always
+ * non-empty, because the chain default is always present).
  *
  * @throws Error if `chainId` has no entry in `chainIdToChain` — fail fast at
  * the boundary rather than silently building an empty list.
+ *
+ * @remarks
+ * Duplicates are collapsed keeping first position. A caller that names the
+ * chain default explicitly — e.g. `BASE_RPC_URL="https://mainnet.base.org,…"`
+ * to pin it as primary — would otherwise get that URL twice, once from the
+ * override list and once from the always-appended chain default.
  */
 export declare const resolveChainRpcUrls: (chainId: ChainId, options?: CreateChainTransportOptions) => string[];
 /**
@@ -58,9 +103,10 @@ export declare const resolveChainRpcUrls: (chainId: ChainId, options?: CreateCha
  *
  * @param chainId - The chain ID to build a transport for. Must resolve via
  * {@link chainIdToChain}.
- * @param options - Optional caller-supplied overrides.
- * @returns A viem `fallback` transport with `rank: true` for latency-based
- * load balancing and `retryCount: 2` per underlying transport.
+ * @param options - Optional caller-supplied overrides and strategy.
+ * @returns A viem `fallback` transport — rank-enabled under the default
+ * `ranked` strategy, strict-priority under `ordered` — with `retryCount: 2`
+ * per underlying transport.
  *
  * @throws Error if `chainId` has no entry in `chainIdToChain` — fail fast at
  * boundary rather than silently falling through to an empty transport list.
@@ -70,6 +116,14 @@ export declare const resolveChainRpcUrls: (chainId: ChainId, options?: CreateCha
  * const transport = createChainTransport(369, { userUrls: ['https://my-rpc'] })
  * const client = createPublicClient({ chain: pulsechain, transport })
  * ```
+ *
+ * @example Hold a metered provider in reserve behind a free primary.
+ * ```ts
+ * const transport = createChainTransport(8453, {
+ *   userUrls: parseRpcUrlList(process.env.BASE_RPC_URL),
+ *   strategy: 'ordered',
+ * })
+ * ```
  */
 export declare const createChainTransport: (chainId: ChainId, options?: CreateChainTransportOptions) => Transport;
 export {};

package/dist/transports.js

@@ -45,6 +45,51 @@ export const FALLBACK_RPC_URLS = {
     369: ['https://rpc-pulsechain.g4mm4.io'],
     8453: [],
 };
+/**
+ * Validate a candidate URL string with the `URL` constructor.
+ *
+ * @param candidate - Trimmed URL string to validate.
+ * @returns True if `new URL(candidate)` succeeds.
+ */
+const isValidUrl = (candidate) => {
+    if (!candidate)
+        return false;
+    try {
+        // eslint-disable-next-line no-new
+        new URL(candidate);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Parse a comma-separated RPC URL list into an ordered array of valid URLs.
+ *
+ * This is the single parser for every comma-separated RPC env in the repo —
+ * the browser's `VITE_RPC_URLS_<chainId>` and the server's `BASE_RPC_URL` /
+ * `PULSECHAIN_RPC_URL` all share this shape, matching the `PONDER_RPC_URL_*`
+ * convention the indexer already uses.
+ *
+ * @param raw - Raw env value. Missing, blank, and all-invalid inputs yield `[]`
+ * so callers can treat the result as a priority-ordered prefix without
+ * null-checking.
+ * @returns Ordered array of trimmed, validated URL strings.
+ *
+ * @example
+ * ```ts
+ * parseRpcUrlList('https://a.example, https://b.example')
+ * // ['https://a.example', 'https://b.example']
+ * ```
+ */
+export const parseRpcUrlList = (raw) => {
+    if (typeof raw !== 'string' || raw.trim() === '')
+        return [];
+    return raw
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter(isValidUrl);
+};
 /**
  * Resolve the ordered RPC URL list for a chain: caller overrides, then the
  * curated fallback list, then the viem chain default. Exposed for testing
@@ -53,11 +98,17 @@ export const FALLBACK_RPC_URLS = {
  * @param chainId - The chain ID to resolve URLs for. Must resolve via
  * {@link chainIdToChain}.
  * @param options - Optional caller-supplied overrides.
- * @returns Priority-ordered list of valid RPC URLs (always non-empty,
- * because the chain default is always present).
+ * @returns Priority-ordered, de-duplicated list of valid RPC URLs (always
+ * non-empty, because the chain default is always present).
  *
  * @throws Error if `chainId` has no entry in `chainIdToChain` — fail fast at
  * the boundary rather than silently building an empty list.
+ *
+ * @remarks
+ * Duplicates are collapsed keeping first position. A caller that names the
+ * chain default explicitly — e.g. `BASE_RPC_URL="https://mainnet.base.org,…"`
+ * to pin it as primary — would otherwise get that URL twice, once from the
+ * override list and once from the always-appended chain default.
  */
 export const resolveChainRpcUrls = (chainId, options = {}) => {
     const chain = chainIdToChain.get(chainId);
@@ -67,7 +118,8 @@ export const resolveChainRpcUrls = (chainId, options = {}) => {
     const userUrls = options.userUrls ?? [];
     const curatedFallbacks = FALLBACK_RPC_URLS[chainId] ?? [];
     const defaultUrl = chain.rpcUrls.default.http[0];
-    return [...userUrls, ...curatedFallbacks, defaultUrl].filter((url) => Boolean(url));
+    const ordered = [...userUrls, ...curatedFallbacks, defaultUrl].filter((url) => Boolean(url));
+    return [...new Set(ordered)];
 };
 /**
  * Build a viem transport for the given chain, layering caller overrides on top
@@ -75,9 +127,10 @@ export const resolveChainRpcUrls = (chainId, options = {}) => {
  *
  * @param chainId - The chain ID to build a transport for. Must resolve via
  * {@link chainIdToChain}.
- * @param options - Optional caller-supplied overrides.
- * @returns A viem `fallback` transport with `rank: true` for latency-based
- * load balancing and `retryCount: 2` per underlying transport.
+ * @param options - Optional caller-supplied overrides and strategy.
+ * @returns A viem `fallback` transport — rank-enabled under the default
+ * `ranked` strategy, strict-priority under `ordered` — with `retryCount: 2`
+ * per underlying transport.
  *
  * @throws Error if `chainId` has no entry in `chainIdToChain` — fail fast at
  * boundary rather than silently falling through to an empty transport list.
@@ -87,6 +140,14 @@ export const resolveChainRpcUrls = (chainId, options = {}) => {
  * const transport = createChainTransport(369, { userUrls: ['https://my-rpc'] })
  * const client = createPublicClient({ chain: pulsechain, transport })
  * ```
+ *
+ * @example Hold a metered provider in reserve behind a free primary.
+ * ```ts
+ * const transport = createChainTransport(8453, {
+ *   userUrls: parseRpcUrlList(process.env.BASE_RPC_URL),
+ *   strategy: 'ordered',
+ * })
+ * ```
  */
 export const createChainTransport = (chainId, options = {}) => {
     const urls = resolveChainRpcUrls(chainId, options);
@@ -102,6 +163,15 @@ export const createChainTransport = (chainId, options = {}) => {
     if (transports.length <= 1) {
         return transports[0];
     }
+    // Ordered strategy: strict priority, no ranking. Entry #1 absorbs every
+    // request and later entries are reached only when the ones before them
+    // error. Ranking is not merely unnecessary here — it is actively wrong when
+    // a later entry is metered, because ranking optimises for latency and a paid
+    // endpoint is usually the fastest one in the list, so it would steer traffic
+    // onto exactly the endpoint the ordering was written to protect.
+    if ((options.strategy ?? 'ranked') === 'ordered') {
+        return fallback(transports);
+    }
     // Multi-URL chains: rank-enabled fallback so the fastest healthy endpoint
     // serves traffic. Custom ping uses eth_blockNumber instead of viem's default
     // net_listening — measures actual query latency (not just TCP round-trip) and

package/dist/transports.test.js

@@ -1,7 +1,22 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
 import { base, pulsechain } from 'viem/chains';
-import { createChainTransport, resolveChainRpcUrls, FALLBACK_RPC_URLS, } from './transports.js';
+import { createChainTransport, parseRpcUrlList, resolveChainRpcUrls, FALLBACK_RPC_URLS, } from './transports.js';
+/**
+ * Read the ordered list of RPC URLs a built transport will actually dial.
+ *
+ * Only safe for the `ordered` strategy: instantiating a ranked transport
+ * starts viem's background ranking poll loop, which would leave a live timer
+ * behind for the duration of the test run.
+ */
+const dialledUrls = (transport) => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const instance = transport({});
+    if (instance.config.type === 'http')
+        return [instance.value.url];
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return instance.value.transports.map((t) => t.value?.url);
+};
 describe('transports', () => {
     describe('FALLBACK_RPC_URLS', () => {
         it('lists g4mm4 for PulseChain (369)', () => {
@@ -11,6 +26,26 @@ describe('transports', () => {
             assert.deepEqual(FALLBACK_RPC_URLS[8453], []);
         });
     });
+    describe('parseRpcUrlList', () => {
+        it('returns an empty list for unset, blank, and whitespace-only input', () => {
+            assert.deepEqual(parseRpcUrlList(undefined), []);
+            assert.deepEqual(parseRpcUrlList(null), []);
+            assert.deepEqual(parseRpcUrlList(''), []);
+            assert.deepEqual(parseRpcUrlList('   '), []);
+        });
+        it('preserves author-supplied order — position encodes priority', () => {
+            assert.deepEqual(parseRpcUrlList('https://first.example,https://second.example'), ['https://first.example', 'https://second.example']);
+        });
+        it('trims padding so a human-formatted env list is not silently rejected', () => {
+            assert.deepEqual(parseRpcUrlList(' https://a.example ,  https://b.example  '), ['https://a.example', 'https://b.example']);
+        });
+        it('drops malformed entries instead of handing them to the transport layer', () => {
+            assert.deepEqual(parseRpcUrlList('not-a-url, https://good.example, also bad'), ['https://good.example']);
+        });
+        it('returns an empty list when every entry is malformed, so callers fall through to defaults', () => {
+            assert.deepEqual(parseRpcUrlList('nope, also-nope'), []);
+        });
+    });
     describe('resolveChainRpcUrls', () => {
         it('returns g4mm4 then chain default for PulseChain', () => {
             const urls = resolveChainRpcUrls(369);
@@ -33,6 +68,14 @@ describe('transports', () => {
                 pulsechain.rpcUrls.default.http[0],
             ]);
         });
+        it('collapses a duplicate when the caller names the chain default explicitly', () => {
+            // Pinning the free public endpoint as primary is the whole point of the
+            // ordered strategy; it must not cost a second, redundant transport.
+            const urls = resolveChainRpcUrls(8453, {
+                userUrls: [base.rpcUrls.default.http[0], 'https://metered.example'],
+            });
+            assert.deepEqual(urls, [base.rpcUrls.default.http[0], 'https://metered.example']);
+        });
         it('throws for unknown chain ID rather than silently returning a single URL', () => {
             assert.throws(() => resolveChainRpcUrls(99999), /no chain definition for chainId 99999/);
         });
@@ -49,5 +92,34 @@ describe('transports', () => {
         it('throws for unknown chain ID via resolveChainRpcUrls', () => {
             assert.throws(() => createChainTransport(99999), /no chain definition for chainId 99999/);
         });
+        it('keeps a metered reserve in second position under the ordered strategy', () => {
+            // Regression guard for the cost bug this strategy exists to prevent:
+            // ranking picks the *fastest* endpoint, and a paid provider is usually
+            // the fastest in the list, so a ranked transport would steer traffic
+            // onto exactly the endpoint the ordering was written to protect.
+            const transport = createChainTransport(8453, {
+                userUrls: [base.rpcUrls.default.http[0], 'https://metered.example'],
+                strategy: 'ordered',
+            });
+            assert.deepEqual(dialledUrls(transport), [
+                base.rpcUrls.default.http[0],
+                'https://metered.example',
+            ]);
+        });
+        it('skips the fallback wrapper when only one endpoint survives resolution', () => {
+            const transport = createChainTransport(8453, {
+                userUrls: [base.rpcUrls.default.http[0]],
+                strategy: 'ordered',
+            });
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            assert.equal(transport({}).config.type, 'http');
+        });
+        it('ignores malformed overrides end-to-end rather than dialling them', () => {
+            const transport = createChainTransport(8453, {
+                userUrls: parseRpcUrlList('garbage, https://metered.example'),
+                strategy: 'ordered',
+            });
+            assert.ok(!dialledUrls(transport).includes('garbage'));
+        });
     });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@provex/utils",
-  "version": "1.9.2-rc.20260721051954.c2db778",
+  "version": "1.9.2-rc.20260722211737.69a2b06",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",