@gibs/common 1.18.0 → 1.20.0

package/dist/assert.js

@@ -1,25 +1,9 @@
-/**
- * Asserts that a value is defined (not null, undefined, or falsy)
- * Throws a descriptive error if the value is falsy
- *
- * @param value - The value to check
- * @param context - Context description for the error message
- * @returns The value if defined
- * @throws Error if value is falsy
- */
 export function ensureResult(value, context) {
     if (!value) {
         throw new Error(`${context}: Expected result but got ${value}`);
     }
     return value;
 }
-/**
- * Type guard that asserts a value is defined
- * Similar to ensureResult but uses TypeScript's asserts syntax
- *
- * @param value - The value to check
- * @param message - Error message if assertion fails
- */
 export function assertDefined(value, message) {
     if (value === null || value === undefined) {
         throw new Error(message);

package/dist/cache.js

@@ -1,10 +1,4 @@
 import { jsonAnyStringify } from './serialize.js';
-/**
- * Memoize a function result and return a single value
- * @param fn the function to memoize
- * @param max the maximum number of values to cache
- * @returns the memoized function
- */
 export const maxMemoize = (fn, max = 1024) => {
     const cache = new Map();
     return (...a) => {
@@ -24,12 +18,6 @@ export const maxMemoize = (fn, max = 1024) => {
     };
 };
 const hour1 = 1000 * 60 * 60;
-/**
- * Memoize a function result and return a single value
- * @param fn the function to memoize
- * @param ttl the time to live for the cache
- * @returns the memoized function
- */
 export const ttlMemoizeSingle = (fn, ttl = hour1) => {
     let cache = null;
     return (...a) => {
@@ -42,23 +30,9 @@ export const ttlMemoizeSingle = (fn, ttl = hour1) => {
         return result;
     };
 };
-/**
- * Memoizes a function under a key the caller computes from its arguments.
- *
- * This is the subset of `lodash.memoize` the packages used: one answer per
- * key, never expired, with `cache.delete` and `cache.clear` for eviction. As
- * with lodash, the `cache` property may be replaced outright. It
- * exists so the published packages carry no lodash-es, whose ECMAScript-module
- * only build a React Native jest run cannot load from `node_modules`.
- *
- * @param fn - the function to memoize
- * @param resolver - computes the cache key from the arguments
- * @returns the memoized function, with its `cache`
- */
 export const memoizeByKey = (fn, resolver) => {
     const memoized = Object.assign((...args) => {
         const key = resolver(...args);
-        // Read the property on every call: a caller may have replaced the Map.
         const { cache } = memoized;
         if (cache.has(key)) {
             return cache.get(key);

package/dist/cjs/assert.js

@@ -2,28 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ensureResult = ensureResult;
 exports.assertDefined = assertDefined;
-/**
- * Asserts that a value is defined (not null, undefined, or falsy)
- * Throws a descriptive error if the value is falsy
- *
- * @param value - The value to check
- * @param context - Context description for the error message
- * @returns The value if defined
- * @throws Error if value is falsy
- */
 function ensureResult(value, context) {
     if (!value) {
         throw new Error(`${context}: Expected result but got ${value}`);
     }
     return value;
 }
-/**
- * Type guard that asserts a value is defined
- * Similar to ensureResult but uses TypeScript's asserts syntax
- *
- * @param value - The value to check
- * @param message - Error message if assertion fails
- */
 function assertDefined(value, message) {
     if (value === null || value === undefined) {
         throw new Error(message);

package/dist/cjs/cache.js

@@ -2,12 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.memoizeByKey = exports.ttlMemoizeSingle = exports.maxMemoize = void 0;
 const serialize_js_1 = require("./serialize.js");
-/**
- * Memoize a function result and return a single value
- * @param fn the function to memoize
- * @param max the maximum number of values to cache
- * @returns the memoized function
- */
 const maxMemoize = (fn, max = 1024) => {
     const cache = new Map();
     return (...a) => {
@@ -28,12 +22,6 @@ const maxMemoize = (fn, max = 1024) => {
 };
 exports.maxMemoize = maxMemoize;
 const hour1 = 1000 * 60 * 60;
-/**
- * Memoize a function result and return a single value
- * @param fn the function to memoize
- * @param ttl the time to live for the cache
- * @returns the memoized function
- */
 const ttlMemoizeSingle = (fn, ttl = hour1) => {
     let cache = null;
     return (...a) => {
@@ -47,23 +35,9 @@ const ttlMemoizeSingle = (fn, ttl = hour1) => {
     };
 };
 exports.ttlMemoizeSingle = ttlMemoizeSingle;
-/**
- * Memoizes a function under a key the caller computes from its arguments.
- *
- * This is the subset of `lodash.memoize` the packages used: one answer per
- * key, never expired, with `cache.delete` and `cache.clear` for eviction. As
- * with lodash, the `cache` property may be replaced outright. It
- * exists so the published packages carry no lodash-es, whose ECMAScript-module
- * only build a React Native jest run cannot load from `node_modules`.
- *
- * @param fn - the function to memoize
- * @param resolver - computes the cache key from the arguments
- * @returns the memoized function, with its `cache`
- */
 const memoizeByKey = (fn, resolver) => {
     const memoized = Object.assign((...args) => {
         const key = resolver(...args);
-        // Read the property on every call: a caller may have replaced the Map.
         const { cache } = memoized;
         if (cache.has(key)) {
             return cache.get(key);

package/dist/cjs/client.js

@@ -6,120 +6,33 @@ const rpcPacer_js_1 = require("./rpcPacer.js");
 const url_js_1 = require("./url.js");
 var rpcPacer_js_2 = require("./rpcPacer.js");
 Object.defineProperty(exports, "MAX_SAME_METHOD_CALLS_PER_SECOND", { enumerable: true, get: function () { return rpcPacer_js_2.MAX_SAME_METHOD_CALLS_PER_SECOND; } });
-/**
- * JSON-RPC request batching config. When enabled, viem coalesces requests made
- * within `wait` milliseconds (up to `batchSize`) into ONE HTTP POST carrying a
- * JSON-RPC array body. This is the default because it sharply cuts request
- * volume on nodes that support it.
- *
- * Note: some public nodes (notably some Binance Smart Chain endpoints) reject the
- * array-wrapped body — even for a single request — which makes every call fail
- * and get retried, BURNING through requests. Such chains must construct their
- * client with `batch: false` (see {@link clientFromChain}'s `batch` option) so
- * requests are sent as plain JSON-RPC objects the node accepts.
- */
 exports.defaultRpcBatch = {
     wait: 10,
     batchSize: 32,
 };
-/** The default batch config for the client */
 exports.defaultBatchConfig = {
     batch: exports.defaultRpcBatch,
 };
-/**
- * Returns the chain key for the given chain id and urls
- * @param chainId - the chain id
- * @param urls - the urls
- * @returns the chain key
- */
 const chainKey = (chainId, urls) => {
     return `${chainId},${urls.join(',')}`.toLowerCase();
 };
 exports.chainKey = chainKey;
-/** The client cache for the given chain id */
 exports.clientCache = new Map();
-/**
- * Returns the client for the given chain and urls
- * @param chain - the chain
- * @param urls - the urls
- * @returns the client
- */
-/**
- * The one pacer for the whole application.
- *
- * MODULE LEVEL, DELIBERATELY. The endpoint keys its budget on the METHOD, not
- * the chain — six `eth_blockNumber` on PulseChain plus six on Ethereum were
- * answered exactly eight times, the same as twelve on one chain. A pacer per
- * client would let two chains spend one budget twice and neither would know it
- * had.
- *
- * It is built with the same ceiling the batch size uses, so the two can never
- * describe different limits.
- */
 const pacer = (0, rpcPacer_js_1.createRpcPacer)({ ceiling: rpcPacer_js_1.MAX_SAME_METHOD_CALLS_PER_SECOND });
-/**
- * Holds a request until its methods fit under the ceiling.
- *
- * WIRED HERE RATHER THAN AROUND THE CALLERS because this is the only place that
- * sees the FINAL body: viem coalesces separate reads into one post, so a limiter
- * upstream of the transport would count intentions and this counts what is
- * actually sent.
- *
- * Returning nothing leaves the request untouched — the hook exists to delay, not
- * to rewrite.
- */
 const paceRequest = async (request) => {
-    // The HOST, not the full url: one proxy serves every chain from one budget,
-    // so `/evm/1` and `/evm/369` must count against the same tally.
     const { host } = (0, url_js_1.splitUrl)(request.url);
     await pacer.reserve(host, (0, rpcPacer_js_1.countMethods)(await request.clone().text().catch(() => null)));
 };
-/**
- * Spreads requests across a chain's endpoints instead of resting on the first.
- *
- * WHAT `fallback` ACTUALLY DOES, and why it is not this. With `rank: false` it
- * sends every request to entry zero and moves on only when that entry ERRORS. So
- * the spares behind a chain carry no load at all: on Ethereum, `valve.city` took
- * one hundred percent of every read while two perfectly good nodes sat idle, and
- * the only way traffic ever reached them was a refusal — a wasted round trip
- * spent discovering a spare we could have used on purpose.
- *
- * That matters because the first entry is a SHARED proxy. Its key is published
- * on chainlist.org, so its per-second budget is not ours alone: measured at a
- * refusal, our own calls in the preceding second were seven against a ceiling of
- * eight. We were not over the limit. Somebody else was using the rest of it, and
- * no amount of pacing on our side fixes that — only using less of that host
- * does.
- *
- * ROUND ROBIN, AND FALLBACK STILL INTACT. Each request starts at the next
- * endpoint in rotation and walks the rest on failure, so a dead host costs one
- * attempt exactly as it did before while a healthy one now carries its share.
- *
- * NOT `rank: true`, which is viem's own answer to this and is the wrong one
- * here: ranking pings EVERY url on EVERY chain every few seconds forever, which
- * on an idle page was once the entire outbound traffic and is what spent the
- * shared budget in the first place. It also reorders a list this project curates
- * deliberately.
- */
 const balanced = (transports) => {
     if (transports.length === 1)
         return transports[0];
     return (config) => {
         const instances = transports.map((transport) => transport(config));
-        // Module-level rotation per client, not per call site: every reader on the
-        // page shares one cursor, which is what makes the split even rather than
-        // each caller starting at zero and piling onto the same host.
         let cursor = 0;
         return (0, viem_1.createTransport)({
             key: 'balanced',
             name: 'Balanced',
             type: 'balanced',
-            // CAST AT THE BOUNDARY, deliberately. `EIP1193RequestFn` is generic over
-            // the method being called and resolves its own return type; a rotation
-            // cannot preserve that relationship because it does not know which
-            // transport will answer until it has tried one. The delegates below are
-            // fully typed and the shape passing through is unchanged — only the
-            // compiler's ability to follow it across the loop is lost.
             request: (async (args) => {
                 const start = cursor;
                 cursor = (cursor + 1) % instances.length;
@@ -129,10 +42,6 @@ const balanced = (transports) => {
                         return await instances[(start + offset) % instances.length].request(args);
                     }
                     catch (error) {
-                        // KEPT AND RETHROWN AT THE END, not swallowed. If every endpoint
-                        // refuses, the caller must see a real error — a rotation that
-                        // returns undefined when all its hosts are down turns an outage
-                        // into a silently empty read.
                         lastError = error;
                     }
                 }

package/dist/cjs/erc20.js

@@ -4,19 +4,11 @@ exports.multicallErc20 = exports.erc20MetadataCalls = void 0;
 const viem_1 = require("viem");
 const cache_js_1 = require("./cache.js");
 const multicall_js_1 = require("./multicall.js");
-/** The erc20 metadata calls */
 exports.erc20MetadataCalls = [
     { functionName: 'name' },
     { functionName: 'symbol' },
     { functionName: 'decimals' },
 ];
-/**
- * The multicall for the erc20 metadata.
- *
- * The annotation spells out the plain call signature, which keeps the
- * memoization an implementation detail: no caller touches the `.cache`
- * property it would otherwise publish.
- */
 exports.multicallErc20 = (0, cache_js_1.memoizeByKey)(async ({ client, target, chain }) => {
     const options = {
         chain: chain,

package/dist/cjs/multicall.js

@@ -3,91 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.multicallRead = exports.chunkBySize = exports.multicallLimits = void 0;
 const viem_1 = require("viem");
 const assert_js_1 = require("./assert.js");
-/**
- * The largest request body the leading endpoint accepts, in bytes. MEASURED,
- * not assumed.
- *
- * `one.valve.city` answers a 102,400 byte body with 200 and a 102,656 byte body
- * with 413, bisected on 2026-09-12. That is the 100 kibibyte default of
- * `express.json`, and the proxy leads every chain list this application ships,
- * so it is the number every other budget here has to clear.
- *
- * THE PREVIOUS VALUE WAS A GUESS AND IT WAS FIVE TIMES TOO LARGE. It said "the
- * one-megabyte body limit that is the default in the reverse proxies these
- * endpoints sit behind", which is Nginx's default, not Express's — and the
- * endpoint in front is Express. Nobody had asked the endpoint.
- */
 const ENDPOINT_BODY_LIMIT_BYTES = 100 * 1024;
-/**
- * How large a single HTTP request body to the node may get, in bytes.
- *
- * Nothing bounded this before, so the whole call list went out at once and the
- * size followed whatever the caller happened to be reading. The token picker
- * reads a balance per token, and PulseChain's list runs to about eleven and a
- * half thousand of them: a single 8.5 MB `eth_call`, repeated on every open,
- * which `rpc.pulsechain.com` answered with HTTP 413. The caller catches that and
- * falls back to an empty map, so the visible result was not an error — it was
- * every balance quietly missing.
- *
- * Four kibibytes under {@link ENDPOINT_BODY_LIMIT_BYTES}, because the budget
- * below counts only the calls: `aggregate3` adds a fixed header of its own and
- * the JSON-RPC envelope wraps the lot, and neither is charged to a call.
- */
 const HTTP_BODY_TARGET_BYTES = ENDPOINT_BODY_LIMIT_BYTES - 4 * 1024;
-/**
- * How many chunks may be in flight at once.
- *
- * Splitting a request is only an improvement if the pieces do not arrive as a
- * burst; an endpoint that rejected one large body will just as happily rate-limit
- * two dozen small ones.
- *
- * ONE, AND RUNNING MORE BUYS NOTHING. The transport coalesces calls made in the
- * same tick into one post, so four chunks at a quarter of the budget each arrive
- * as ONE post of the same total size as a single full-budget chunk — the same
- * bytes, in the same round trip, at four times the call count. The proxy's
- * budget counts CALLS, not posts and not bytes, so the wider setting spent four
- * times the rate limit for identical throughput.
- *
- * Measured on one token-picker open, 2026-09-12: at a concurrency of four the
- * peak was eleven calls of one method in a second against a ceiling of eight,
- * and one post was refused; at one the peak was seven and every post was
- * answered. Request bytes fell from 737,057 to 638,890 in the same comparison,
- * because nothing had to be resent to a fallback endpoint.
- */
 const CHUNK_CONCURRENCY = 1;
-/**
- * How much encoded call data one `aggregate3` may carry.
- *
- * Divided by the concurrency rather than set directly, because the transport
- * COALESCES calls made in the same tick into one HTTP body. Chunking to a
- * quarter-megabyte budget and running four at a time was measured arriving as a
- * single 1.37 MB request — the split was real, and then undone at the layer
- * below. What the node sees is this budget multiplied by the concurrency, so
- * that is the relationship worth writing down; changing either constant alone
- * cannot silently blow the target.
- *
- * STILL TRUE AT A CONCURRENCY OF ONE, and that is why the division stays rather
- * than being folded away: raising the concurrency again without cutting this
- * budget would put the target back over the endpoint's limit, and the division
- * is what stops that being silent.
- */
 const CALLDATA_BUDGET_BYTES = Math.floor(HTTP_BODY_TARGET_BYTES / CHUNK_CONCURRENCY);
-/**
- * Bytes of request body a single call costs beyond its own encoded data.
- * MEASURED against a real `aggregate3` encoding, not estimated.
- *
- * `aggregate3` spends five thirty-two byte words per call — the head offset, the
- * target, the failure flag, the data offset and the data length — which is 320
- * hexadecimal characters, plus up to 63 more padding the call data out to a word
- * boundary. A `balanceOf` whose own call data is 74 characters was measured
- * costing 448.6 bytes of body, so the real overhead is about 375 and the old
- * value of 200 UNDERSTATED IT BY NEARLY A HALF.
- *
- * That is how a chunk budgeted at 128 kibibytes went out as a 214 kilobyte body.
- * Four hundred keeps a small margin over the measurement.
- */
 const PER_CALL_OVERHEAD_BYTES = 400;
-/** The size limits, exported so tests assert against the real values. */
 exports.multicallLimits = {
     endpointBodyLimitBytes: ENDPOINT_BODY_LIMIT_BYTES,
     httpBodyTargetBytes: HTTP_BODY_TARGET_BYTES,
@@ -95,22 +15,6 @@ exports.multicallLimits = {
     chunkConcurrency: CHUNK_CONCURRENCY,
     perCallOverheadBytes: PER_CALL_OVERHEAD_BYTES,
 };
-/**
- * Splits encoded calls into groups whose combined request body stays under
- * {@link CALLDATA_BUDGET_BYTES}.
- *
- * Grouped by measured size rather than by a fixed count on purpose: callers
- * differ by more than an order of magnitude in how large one call encodes to — a
- * bare `balanceOf` against a router quote carrying a swap path — so any single
- * call limit would be far too cautious for one caller and useless for another.
- *
- * A call that exceeds the budget on its own still gets its own group; splitting
- * it further is not possible, and refusing to send it would turn an oversized
- * request into a missing result.
- *
- * @param encoded - the calls to group, in order
- * @returns groups preserving the original order
- */
 const chunkBySize = (encoded) => {
     const chunks = [];
     let current = [];
@@ -130,14 +34,6 @@ const chunkBySize = (encoded) => {
     return chunks;
 };
 exports.chunkBySize = chunkBySize;
-/**
- * Runs `task` over every item with at most `concurrency` in flight, preserving
- * input order in the result.
- *
- * @param items - the work items
- * @param concurrency - how many may run at once
- * @param task - what to do with one item
- */
 const mapWithConcurrency = async (items, concurrency, task) => {
     const results = new Array(items.length);
     let next = 0;
@@ -151,33 +47,16 @@ const mapWithConcurrency = async (items, concurrency, task) => {
     await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, worker));
     return results;
 };
-/**
- * Reads many contract calls through Multicall3, splitting the work across as
- * many requests as the size budget needs and reassembling the results in order.
- *
- * Chunking is invisible to callers: the returned array lines up with `calls`
- * one-for-one exactly as it did when every call went out together, and a chunk
- * that rejects still rejects the whole read rather than returning a short array
- * that a caller would silently misread as "these tokens have no balance".
- *
- * @param options.chain - the chain, used for its Multicall3 deployment
- * @param options.client - the public client to read through
- * @param options.abi - the default ABI, when a call does not carry its own
- * @param options.calls - the calls to make, in the order results are wanted
- * @param options.target - the default contract, when a call does not name one
- */
 const multicallRead = async ({ chain, client, abi, calls, target, }) => {
     const multicall = (0, viem_1.getContract)({
         abi: viem_1.multicall3Abi,
         address: chain.contracts.multicall3.address,
-        // this seems like a bug in viem, it should be able to infer the type of the client
         client: client,
     });
     const arg = calls.map((call) => ({
         callData: (0, viem_1.encodeFunctionData)({
             abi: call.abi || abi,
             functionName: call.functionName,
-            // this seems like a bug in viem, it should be able to infer the type of the args
             args: (call.args || []),
         }),
         allowFailure: call.allowFailure || false,
@@ -202,9 +81,6 @@ const multicallRead = async ({ chain, client, abi, calls, target, }) => {
             }));
     }
     catch (err) {
-        // Deliberately a summary rather than the calls themselves: a failing read can
-        // hold tens of thousands of them, and dumping the array cost more than the
-        // failure did.
         console.error('Multicall aggregate3 failed', {
             chainId: client.chain?.id,
             target,

package/dist/cjs/rpcPacer.js

@@ -1,81 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.countMethods = exports.createRpcPacer = exports.MAX_SAME_METHOD_CALLS_PER_SECOND = void 0;
-/**
- * Holds outgoing JSON-RPC requests back so no method crosses the endpoint's
- * per-second ceiling.
- *
- * WHY BATCH SIZE WAS NOT ENOUGH, WHICH IS THE WHOLE POINT OF THIS FILE. The
- * transport already caps a single post at the ceiling, and that stops one post
- * being refused for being too big. It says nothing about how many posts leave
- * per second. Measured on one page load: nine `eth_call` inside a single rolling
- * second, spread across four posts of which none was individually too large, and
- * the fourth came back `429`.
- *
- * A ROLLING WINDOW, NOT A BUCKET. The first measurement of this counted calls
- * into whole seconds aligned to the page load and reported nothing over the
- * ceiling while a refusal sat in the same run — six calls at 1.9 seconds and
- * seven at 2.1 fall in different buckets and land 200 milliseconds apart. A rate
- * limiter does not know when our page started, so neither does this.
- *
- * ONE LIMITER FOR THE WHOLE APPLICATION, not one per client — but keyed on the
- * HOST as well as the method.
- *
- * The budget is the host's, and it is shared across chains: six
- * `eth_blockNumber` on PulseChain plus six on Ethereum were answered exactly
- * eight times, the same as twelve on one chain. So a limiter per client would
- * let two chains spend one budget twice and neither would know.
- *
- * But two DIFFERENT hosts have two different budgets, and counting them
- * together would throttle a spare endpoint for traffic it never received —
- * which is exactly backwards once requests are spread across hosts on purpose.
- */
-/**
- * The most calls of ONE method the proxy answers in one second. MEASURED.
- *
- * `one.valve.city` refuses past this with HTTP 429 and the body
- * `Rate limit exceeded (per method, per second)`. Probed 2026-09-12 at
- * concurrency 1, 2, 3, 4, 6, 8, 12, 16 and 24: every request up to eight was
- * answered and everything past eight was refused, with no variance across
- * twenty rounds. The budget is shared across CHAINS — six calls on chain 369
- * plus six on chain 1 were answered exactly eight times, the same as twelve on
- * one chain — so it is keyed on the method, not the chain.
- *
- * A BATCH THAT CROSSES THE CEILING IS REFUSED WHOLE, which is why this bounds
- * the batch size. One post carrying sixteen `eth_blockNumber` calls came back
- * with all sixteen refused; the same sixteen sent as separate posts had eight
- * answered. Coalescing past the ceiling therefore converts a partial refusal
- * into a total one, and viem's default of thirty-two calls per post is four
- * times over it.
- */
 exports.MAX_SAME_METHOD_CALLS_PER_SECOND = 8;
 const systemClock = {
     now: () => Date.now(),
     sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
 };
-/** The window the ceiling is counted over. */
 const WINDOW_MS = 1_000;
-/**
- * Builds a pacer.
- *
- * @param options - the ceiling, and optionally a clock to drive it.
- * @returns a pacer.
- */
 const createRpcPacer = ({ ceiling, clock = systemClock, }) => {
-    /** When each still-counting call was sent, per host-and-method, oldest first. */
     const sent = new Map();
-    /**
-     * Reservations run ONE AT A TIME, chained. Two callers checking the window
-     * concurrently both see room and both take it — the classic check-then-act
-     * race, and the reason a limiter that looks right can still emit bursts. The
-     * chain makes "is there room" and "take it" a single step.
-     */
     let queue = Promise.resolve();
     const forget = (method, now) => {
         const times = sent.get(method);
         if (!times)
             return [];
-        // Times are appended in order, so everything expired is a prefix.
         let keep = 0;
         while (keep < times.length && now - times[keep] >= WINDOW_MS)
             keep += 1;
@@ -84,11 +22,6 @@ const createRpcPacer = ({ ceiling, clock = systemClock, }) => {
         return live;
     };
     const reserveOne = async (key, count) => {
-        // A request carrying MORE than the ceiling of one method cannot ever fit,
-        // and waiting for room that will never exist would hang the page forever.
-        // The transport caps a post at the ceiling, so this is a guard against a
-        // caller that bypassed it rather than an expected path: spend what there is
-        // and let the endpoint answer for the rest.
         const want = Math.min(count, ceiling);
         for (;;) {
             const now = clock.now();
@@ -99,9 +32,6 @@ const createRpcPacer = ({ ceiling, clock = systemClock, }) => {
                 sent.set(key, live);
                 return;
             }
-            // Wait exactly until the oldest call leaves the window — not a fixed
-            // retry interval, which would either spin or overshoot. The `+ 1` is so
-            // the comparison above is past the boundary rather than on it.
             const oldest = live[0];
             await clock.sleep(Math.max(1, oldest + WINDOW_MS - now + 1));
         }
@@ -109,15 +39,10 @@ const createRpcPacer = ({ ceiling, clock = systemClock, }) => {
     return {
         reserve: (host, counts) => {
             const run = queue.then(async () => {
-                // Ordered so the same body always reserves its methods in the same
-                // sequence; two bodies reserving the same pair in opposite orders is
-                // how a queue deadlocks itself.
                 for (const method of [...counts.keys()].sort()) {
                     await reserveOne(`${host}|${method}`, counts.get(method) ?? 0);
                 }
             });
-            // The queue must continue even when a reservation throws, or one failure
-            // stops every later request on the page.
             queue = run.catch(() => undefined);
             return run;
         },
@@ -125,16 +50,6 @@ const createRpcPacer = ({ ceiling, clock = systemClock, }) => {
     };
 };
 exports.createRpcPacer = createRpcPacer;
-/**
- * Counts the calls per method in a JSON-RPC body.
- *
- * A batch is an ARRAY and a single call is an object; both arrive here, and a
- * body that cannot be read at all counts as nothing rather than throwing —
- * pacing is an optimisation and must never be the reason a request fails.
- *
- * @param body - the request body, as text.
- * @returns method to how many calls of it the body carries.
- */
 const countMethods = (body) => {
     const counts = new Map();
     if (!body)

package/dist/cjs/serialize.js

@@ -2,7 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.jsonAnyParse = exports.isSerializedBigInt = exports.jsonAnyStringify = void 0;
 const BIGINT_TYPE = 'bigint';
-/** The json any stringify for the given key and value */
 const jsonAnyStringify = (_key, value) => {
     if (typeof value === BIGINT_TYPE) {
         return {
@@ -13,29 +12,11 @@ const jsonAnyStringify = (_key, value) => {
     return value;
 };
 exports.jsonAnyStringify = jsonAnyStringify;
-/** The is serialized big int for the given value */
 const isSerializedBigInt = (value) => {
     return (!!value && typeof value === 'object' && value.__type__ === BIGINT_TYPE);
 };
 exports.isSerializedBigInt = isSerializedBigInt;
-/**
- * The only strings `jsonAnyStringify` ever writes: what `bigint.toString()`
- * produces, which is an optional minus sign followed by decimal digits.
- *
- * Anything else in the `value` field means the record is corrupt, and `BigInt`
- * is too permissive to notice. `BigInt('')` is 0n and `BigInt('0x10')` is 16n,
- * so a truncated or garbled record parses into a plausible-looking balance
- * instead of an error — and a wrong balance is spent, displayed and believed.
- */
 const DECIMAL_BIG_INT = /^-?\d+$/;
-/**
- * The json any parse for the given key and value.
- *
- * Throws on a corrupt encoded value rather than returning a number for it. Every
- * caller reads from local storage inside a try/catch and falls back to a
- * default, so a throw discards one unusable record; a silent zero would survive
- * into the arithmetic.
- */
 const jsonAnyParse = (_key, value) => {
     if ((0, exports.isSerializedBigInt)(value)) {
         if (typeof value.value !== 'string' || !DECIMAL_BIG_INT.test(value.value)) {