@provex/utils 1.11.0 → 2.0.0

package/dist/transports.debug.test.js

@@ -0,0 +1,95 @@
+/**
+ * @fileoverview Tests for the RPC call counter, the ranking probe and the
+ * environment-dependent default strategy.
+ *
+ * The counter exists so a developer can open a browser console, set
+ * `window.__RPC_DEBUG = true`, and see which JSON-RPC methods a page is
+ * hammering. It must stay silent otherwise and must never fail a request.
+ */
+import { afterEach, describe, it, mock } from 'node:test';
+import assert from 'node:assert/strict';
+import { base } from 'viem/chains';
+import { createChainTransport, defaultChainTransportStrategy, logRpcRequest, pingBlockNumber, } from './transports.js';
+const windowHost = globalThis;
+const jsonRequest = (method) => new Request('https://rpc.example', { method: 'POST', body: JSON.stringify({ jsonrpc: '2.0', id: 1, method }) });
+/** Let the fire-and-forget body read finish. */
+const settle = () => new Promise((resolve) => setTimeout(resolve, 10));
+afterEach(() => {
+    delete windowHost.window;
+    mock.restoreAll();
+});
+describe('logRpcRequest', () => {
+    it('stays silent when the debug flag is not set, so production consoles stay clean', async () => {
+        const debug = mock.method(console, 'debug', () => { });
+        logRpcRequest(jsonRequest('eth_chainId'));
+        await settle();
+        assert.equal(debug.mock.callCount(), 0);
+    });
+    it('stays silent when window exists but the flag is not exactly true', async () => {
+        windowHost.window = { __RPC_DEBUG: undefined };
+        const debug = mock.method(console, 'debug', () => { });
+        logRpcRequest(jsonRequest('eth_chainId'));
+        await settle();
+        assert.equal(debug.mock.callCount(), 0);
+    });
+    it('logs each method with a running per-method count when the flag is set', async () => {
+        windowHost.window = { __RPC_DEBUG: true };
+        const debug = mock.method(console, 'debug', () => { });
+        logRpcRequest(jsonRequest('eth_getLogs'));
+        logRpcRequest(jsonRequest('eth_getLogs'));
+        await settle();
+        assert.equal(debug.mock.callCount(), 2);
+        const lastLine = String(debug.mock.calls[1].arguments[0]);
+        assert.match(lastLine, /^\[RPC\] eth_getLogs \| 2 calls in [\d.]+s \| window: /);
+        assert.match(lastLine, /"eth_getLogs":2/);
+    });
+    it('leaves the original request body readable, because viem still has to send it', async () => {
+        const request = jsonRequest('eth_chainId');
+        logRpcRequest(request);
+        await settle();
+        assert.equal(request.bodyUsed, false);
+        assert.equal((await request.json()).method, 'eth_chainId');
+    });
+    it('ignores a body that is not JSON instead of failing the request', async () => {
+        windowHost.window = { __RPC_DEBUG: true };
+        const debug = mock.method(console, 'debug', () => { });
+        const request = new Request('https://rpc.example', { method: 'POST', body: 'not json' });
+        assert.doesNotThrow(() => logRpcRequest(request));
+        await settle();
+        assert.equal(debug.mock.callCount(), 0);
+    });
+});
+describe('pingBlockNumber', () => {
+    it('probes with eth_blockNumber and returns its answer', async () => {
+        const calls = [];
+        const result = await pingBlockNumber({
+            transport: {
+                request: async (args) => {
+                    calls.push(args);
+                    return '0x10';
+                },
+            },
+        });
+        assert.deepEqual(calls, [{ method: 'eth_blockNumber', params: [] }]);
+        assert.equal(result, '0x10');
+    });
+});
+describe('defaultChainTransportStrategy', () => {
+    it('is ordered in Node, because ranking would keep the process alive forever', () => {
+        assert.equal(defaultChainTransportStrategy(), 'ordered');
+    });
+    it('is ranked in a browser, where the page owns the client for its lifetime', () => {
+        windowHost.window = {};
+        assert.equal(defaultChainTransportStrategy(), 'ranked');
+    });
+});
+describe('createChainTransport with an explicit ranked strategy', () => {
+    it('builds a factory without starting the ranking poller until a client uses it', () => {
+        // The poller starts when viem calls the factory with a chain, not here.
+        const transport = createChainTransport(8453, {
+            userUrls: [base.rpcUrls.default.http[0], 'https://other.example'],
+            strategy: 'ranked',
+        });
+        assert.equal(typeof transport, 'function');
+    });
+});

package/dist/transports.js

@@ -46,6 +46,27 @@ const _rpcLog = (method) => {
     const elapsed = ((now - _rpcLastWindow) / 1000).toFixed(1);
     console.debug(`[RPC] ${method} | ${total} calls in ${elapsed}s | window: ${JSON.stringify(_rpcCounts)}`);
 };
+/**
+ * Count one outgoing JSON-RPC request for the debug log.
+ *
+ * Reads the method from a clone, so the real request body stays unread. A body
+ * that is not JSON is ignored: a debug counter must never fail a request.
+ *
+ * @param req - The request viem is about to send.
+ */
+export const logRpcRequest = (req) => {
+    void req.clone().json().then((body) => _rpcLog(body.method)).catch(() => { });
+};
+/**
+ * Latency probe for ranked transports: one `eth_blockNumber` call.
+ *
+ * It measures real query latency, not just the TCP round trip, and avoids the
+ * noisy `net_listening` entries viem's default probe leaves in server logs.
+ *
+ * @param transport - The transport instance viem is ranking.
+ * @returns The block number response, which viem times and discards.
+ */
+export const pingBlockNumber = (transport) => transport.transport.request({ method: 'eth_blockNumber', params: [] });
 /**
  * Provex-curated fallback RPC URLs per chain, applied after caller overrides
  * but before the viem chain default.
@@ -135,7 +156,7 @@ export const parseRpcUrlList = (raw) => {
  * browser (a long-running Node service) can still pass `strategy: 'ranked'`
  * explicitly.
  */
-const defaultStrategy = () => typeof window === 'undefined' ? 'ordered' : 'ranked';
+export const defaultChainTransportStrategy = () => typeof window === 'undefined' ? 'ordered' : 'ranked';
 /**
  * Resolve the ordered RPC URL list for a chain: caller overrides, then the
  * curated fallback list, then the viem chain default. Exposed for testing
@@ -162,7 +183,7 @@ export const resolveChainRpcUrls = (chainId, options = {}) => {
         throw new Error(`resolveChainRpcUrls: no chain definition for chainId ${chainId}`);
     }
     const userUrls = options.userUrls ?? [];
-    const curatedFallbacks = FALLBACK_RPC_URLS[chainId] ?? [];
+    const curatedFallbacks = FALLBACK_RPC_URLS[chainId];
     const defaultUrl = chain.rpcUrls.default.http[0];
     const ordered = [...userUrls, ...curatedFallbacks, defaultUrl].filter((url) => Boolean(url));
     return [...new Set(ordered)];
@@ -197,12 +218,7 @@ export const resolveChainRpcUrls = (chainId, options = {}) => {
  */
 export const createChainTransport = (chainId, options = {}) => {
     const urls = resolveChainRpcUrls(chainId, options);
-    const transports = urls.map((url) => http(url, {
-        retryCount: 2,
-        onFetchRequest: (req) => {
-            void req.clone().json().then((body) => _rpcLog(body.method ?? '?')).catch(() => { });
-        },
-    }));
+    const transports = urls.map((url) => http(url, { retryCount: 2, onFetchRequest: logRpcRequest }));
     // Single-URL chains: return the transport directly. fallback([single]) adds
     // overhead with no benefit — there's nothing to fall back to, and retryCount
     // is already set on the http() call above.
@@ -215,7 +231,7 @@ export const createChainTransport = (chainId, options = {}) => {
     // 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 ?? defaultStrategy()) === 'ordered') {
+    if ((options.strategy ?? defaultChainTransportStrategy()) === 'ordered') {
         return fallback(transports);
     }
     // Multi-URL chains: rank-enabled fallback so the fastest healthy endpoint
@@ -230,7 +246,7 @@ export const createChainTransport = (chainId, options = {}) => {
         rank: {
             interval: 60_000,
             sampleCount: 3,
-            ping: (t) => t.transport.request({ method: 'eth_blockNumber', params: [] }),
+            ping: pingBlockNumber,
         },
     });
 };

package/dist/transports.test.js

@@ -56,6 +56,9 @@ describe('transports', () => {
         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('skips the empty slots a stray or trailing comma leaves behind', () => {
+            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']);
         });
@@ -167,7 +170,8 @@ describe('process liveness — the ranking poller has no off switch', () => {
         // must still terminate; when it did not, three test files hung for their
         // full timeout with every assertion passing, and
         // `packages/scripts/src/lookup-hash.ts` grew a hand-added `process.exit(0)`.
-        assert.equal(buildsAndExits(undefined, 30_000), true, 'building a default transport left the process alive');
+        // Generous timeout: a loaded machine can take over a minute to start the child.
+        assert.equal(buildsAndExits(undefined, 120_000), true, 'building a default transport left the process alive');
     });
     it('does not exit when ranking is explicitly requested', () => {
         // The counterweight. Without this, the assertion above would still pass if

package/dist/units.d.ts

@@ -99,6 +99,25 @@ export declare const parseUnits: (amount: string, options: Pick<FormatRateDispla
  * ```
  */
 export declare function formatUnits(amount: bigint, options: FormatRateDisplayOptions): string;
+/**
+ * Format a bigint amount as text for an editable field.
+ *
+ * Unlike {@link formatUnits} this never inserts a thousands delimiter, so the
+ * text is legal in an `<input type="number">` and re-parses to the same bigint.
+ * It keeps full precision unless `truncateDecimals` is given.
+ *
+ * @param amount - Amount in base units
+ * @param options - Same options as {@link formatUnits}; `delimiter` is not accepted
+ * @returns Plain decimal text such as `'1234.5'`
+ *
+ * @example
+ * ```ts
+ * formatUnitsForInput(1_234_500000n, { decimals: 6 })                    // '1234.5'
+ * formatUnitsForInput(10_123456n, { decimals: 6, padDecimals: 2 })       // '10.123456'
+ * formatUnitsForInput(500_000000n, { decimals: 6, padDecimals: 2 })      // '500.00'
+ * ```
+ */
+export declare function formatUnitsForInput(amount: bigint, options: Omit<FormatRateDisplayOptions, 'delimiter'>): string;
 /**
  * Format a token amount for display with 2 decimal places.
  * Convenience wrapper around formatUnits with truncateDecimals: 2.

package/dist/units.js

@@ -120,6 +120,27 @@ export function formatUnits(amount, options) {
     const numberString = `${integerPart}.${finalFractionalPart}`;
     return addThousandsSeparator(numberString, delimiter);
 }
+/**
+ * Format a bigint amount as text for an editable field.
+ *
+ * Unlike {@link formatUnits} this never inserts a thousands delimiter, so the
+ * text is legal in an `<input type="number">` and re-parses to the same bigint.
+ * It keeps full precision unless `truncateDecimals` is given.
+ *
+ * @param amount - Amount in base units
+ * @param options - Same options as {@link formatUnits}; `delimiter` is not accepted
+ * @returns Plain decimal text such as `'1234.5'`
+ *
+ * @example
+ * ```ts
+ * formatUnitsForInput(1_234_500000n, { decimals: 6 })                    // '1234.5'
+ * formatUnitsForInput(10_123456n, { decimals: 6, padDecimals: 2 })       // '10.123456'
+ * formatUnitsForInput(500_000000n, { decimals: 6, padDecimals: 2 })      // '500.00'
+ * ```
+ */
+export function formatUnitsForInput(amount, options) {
+    return formatUnits(amount, { ...options, delimiter: '' });
+}
 /**
  * Format a token amount for display with 2 decimal places.
  * Convenience wrapper around formatUnits with truncateDecimals: 2.

package/dist/units.test.js

@@ -1,6 +1,6 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
-import { oneEther, addThousandsSeparator, parseUnits, formatUnits, formatTokenAmountForDisplay, parseIntegerSafe, timestampToDate, formatAmount, abbreviateNumber, formatWithAbbreviation, numericAbbreviations, } from './units.js';
+import { oneEther, addThousandsSeparator, parseUnits, formatUnits, formatUnitsForInput, formatTokenAmountForDisplay, parseIntegerSafe, timestampToDate, formatAmount, abbreviateNumber, formatWithAbbreviation, numericAbbreviations, } from './units.js';
 describe('abbreviateNumber', () => {
     describe('with decimals: 0 (whole numbers)', () => {
         it('should abbreviate thousands with k suffix', () => {
@@ -338,3 +338,33 @@ describe('formatAmount', () => {
         assert.equal(result, '1.2345');
     });
 });
+// A value written into a number input must contain no thousands delimiter and
+// must re-parse to the exact bigint, or the field shows empty / changes the amount.
+describe('formatUnitsForInput', () => {
+    const cases = [
+        ['below one thousand', 999500000n, { decimals: 6 }, '999.5'],
+        ['one thousand or more has no comma', 1234500000n, { decimals: 6 }, '1234.5'],
+        ['millions have no comma', 12345678900000n, { decimals: 6 }, '12345678.9'],
+        ['sub-cent precision is kept', 10123456n, { decimals: 6, padDecimals: 2 }, '10.123456'],
+        ['pads to the requested places', 500000000n, { decimals: 6, padDecimals: 2 }, '500.00'],
+        ['an 18-decimal rate of 1234.5', 1234500000000000000000n, { decimals: 18, padDecimals: 2 }, '1234.50'],
+        ['zero', 0n, { decimals: 6 }, '0'],
+    ];
+    for (const [name, amount, options, expected] of cases) {
+        it(`${name}: ${expected}`, () => {
+            assert.equal(formatUnitsForInput(amount, options), expected);
+            assert.equal(parseUnits(expected, { decimals: options.decimals }), amount);
+        });
+    }
+});
+describe('abbreviateNumber below the first suffix', () => {
+    it('keeps a non-zero fraction so 999.5 is not shown as 999', () => {
+        assert.equal(abbreviateNumber(9995n, { decimals: 1 }), '999.5');
+    });
+    it('keeps the sign on a negative fractional value', () => {
+        assert.equal(abbreviateNumber(-9995n, { decimals: 1 }), '-999.5');
+    });
+    it('drops an all-zero fraction', () => {
+        assert.equal(abbreviateNumber(5000n, { decimals: 1 }), '500');
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@provex/utils",
-  "version": "1.11.0",
+  "version": "2.0.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
@@ -120,13 +120,17 @@
     "./consent": {
       "import": "./dist/consent.js",
       "types": "./dist/consent.d.ts"
+    },
+    "./buy": {
+      "import": "./dist/buy/index.js",
+      "types": "./dist/buy/index.d.ts"
     }
   },
   "scripts": {
     "build": "tsx scripts/convert-svg && tsc && cp -r src/data dist/",
     "test": "node --import tsx --test 'src/**/*.test.ts'",
     "test:watch": "node --import tsx --test --watch 'src/**/*.test.ts'",
-    "test:coverage": "node --import tsx --test --experimental-test-coverage --test-coverage-exclude='src/**/*.test.ts' --test-coverage-exclude='src/data/**' --test-coverage-exclude='src/flags/**' --test-coverage-exclude='src/flags.ts' --test-coverage-exclude='src/global.d.ts' 'src/**/*.test.ts'"
+    "test:coverage": "node --import tsx --test --experimental-test-coverage --test-coverage-lines=100 --test-coverage-branches=100 --test-coverage-functions=100 --test-coverage-exclude='src/**/*.test.ts' --test-coverage-exclude='src/data/**' --test-coverage-exclude='src/flags/**' --test-coverage-exclude='src/flags.ts' --test-coverage-exclude='src/global.d.ts' 'src/**/*.test.ts'"
   },
   "keywords": [],
   "author": "",