@gibs/common 1.18.0 → 1.20.0

package/dist/rpcPacer.js

@@ -1,78 +1,16 @@
-/**
- * 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.
- */
 export const 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.
- */
 export 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;
@@ -81,11 +19,6 @@ export 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();
@@ -96,9 +29,6 @@ export 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));
         }
@@ -106,31 +36,16 @@ export 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;
         },
         spent: (host, method) => forget(`${host}|${method}`, clock.now()).length,
     };
 };
-/**
- * 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.
- */
 export const countMethods = (body) => {
     const counts = new Map();
     if (!body)

package/dist/serialize.js

@@ -1,5 +1,4 @@
 const BIGINT_TYPE = 'bigint';
-/** The json any stringify for the given key and value */
 export const jsonAnyStringify = (_key, value) => {
     if (typeof value === BIGINT_TYPE) {
         return {
@@ -9,28 +8,10 @@ export const jsonAnyStringify = (_key, value) => {
     }
     return value;
 };
-/** The is serialized big int for the given value */
 export const isSerializedBigInt = (value) => {
     return (!!value && typeof value === 'object' && value.__type__ === BIGINT_TYPE);
 };
-/**
- * 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.
- */
 export const jsonAnyParse = (_key, value) => {
     if (isSerializedBigInt(value)) {
         if (typeof value.value !== 'string' || !DECIMAL_BIG_INT.test(value.value)) {

package/dist/url.js

@@ -1,30 +1,6 @@
-/**
- * Request addresses, built and read with plain string work.
- *
- * WHY THIS EXISTS: React Native 0.77 installs its own `URL` and
- * `URLSearchParams` (react-native/Libraries/Blob/URL.js), and both are partial.
- * `new URL(x).protocol`, `.host`, `.pathname` and `.search` throw "not
- * implemented". `searchParams` is always a new, empty list, so a reader of it
- * silently sees no parameters. `URLSearchParams` can only append and
- * serialize: `get`, `set`, `has` and `delete` throw, and a string passed to
- * its constructor is ignored. A package that uses either class needs a
- * polyfill in a wallet. These functions need nothing from the runtime but
- * `encodeURIComponent` and `decodeURIComponent`.
- *
- * Their output matches what the WHATWG classes produce for the addresses the
- * Gibs packages build: a lowercase `http:` or `https:` origin with a plain
- * path. A query is encoded exactly as `URLSearchParams` encodes it, as
- * `application/x-www-form-urlencoded`: a space becomes `+`, and only letters,
- * digits and `*-._` stay as they are. They do not normalize the address
- * itself: an uppercase host or a `..` path segment passes through as written.
- */
-/** A surrogate pair, or a lone surrogate half. */
 const surrogates = /[\uD800-\uDBFF][\uDC00-\uDFFF]|[\uD800-\uDFFF]/g;
-/** The characters `encodeURIComponent` keeps that a form encoder escapes. */
 const formEscapedCharacters = /[!'()~]/g;
-/** A run of percent-encoded bytes. */
 const percentEncodedRun = /(?:%[0-9A-Fa-f]{2})+/g;
-/** The port each special scheme leaves out of its host. */
 const defaultPorts = Object.freeze({
     http: '80',
     https: '443',
@@ -32,38 +8,11 @@ const defaultPorts = Object.freeze({
     wss: '443',
     ftp: '21',
 });
-/**
- * Replaces each lone surrogate half with U+FFFD, as the WHATWG classes do
- * before they encode. `encodeURIComponent` would throw on one instead.
- *
- * @param text - any string
- * @returns the string, well formed
- */
 const toWellFormed = (text) => text.replace(surrogates, (match) => (match.length === 2 ? match : '�'));
-/**
- * Percent-encodes one character as two uppercase hex digits.
- *
- * @param character - a single ASCII character
- * @returns the character as `%XX`
- */
 const percentEncodeCharacter = (character) => `%${character.charCodeAt(0).toString(16).toUpperCase().padStart(2, '0')}`;
-/**
- * Encodes a query name or value exactly as `URLSearchParams.toString` does.
- *
- * @param text - the raw name or value
- * @returns the encoded text
- */
 export const encodeQueryComponent = (text) => encodeURIComponent(toWellFormed(text))
     .replace(formEscapedCharacters, percentEncodeCharacter)
     .replace(/%20/g, '+');
-/**
- * Counts the continuation bytes a UTF-8 lead byte announces, and the bounds
- * the first of them must fall in. The bounds reject overlong forms and
- * surrogates, as the WHATWG decoder does.
- *
- * @param lead - the first byte of a sequence
- * @returns the count, the lead byte's own bits, and the first continuation byte's bounds; null for a byte that cannot start one
- */
 const utf8Lead = (lead) => {
     if (lead >= 0xc2 && lead <= 0xdf)
         return { count: 1, bits: lead & 0x1f, lower: 0x80, upper: 0xbf };
@@ -81,14 +30,6 @@ const utf8Lead = (lead) => {
         return { count: 3, bits: lead & 0x07, lower: 0x80, upper: 0xbf };
     return null;
 };
-/**
- * Decodes UTF-8 bytes as the WHATWG decoder does: each malformed part becomes
- * one U+FFFD, and a byte that ends a malformed part is read again as the
- * start of the next. Only reached when `decodeURIComponent` refuses a run.
- *
- * @param bytes - the bytes
- * @returns the decoded text
- */
 const decodeUtf8Leniently = (bytes) => {
     const decode = (index, decoded) => {
         if (index >= bytes.length)
@@ -116,12 +57,6 @@ const decodeUtf8Leniently = (bytes) => {
     };
     return decode(0, '');
 };
-/**
- * Decodes one run of `%XX` bytes.
- *
- * @param run - consecutive `%XX` sequences
- * @returns the text they encode
- */
 const decodePercentRun = (run) => {
     try {
         return decodeURIComponent(run);
@@ -130,22 +65,7 @@ const decodePercentRun = (run) => {
         return decodeUtf8Leniently(run.slice(1).split('%').map((pair) => Number.parseInt(pair, 16)));
     }
 };
-/**
- * Decodes a query name or value as the WHATWG URL standard says
- * `URLSearchParams` must: `+` is a space, a valid `%XX` is a byte, a `%` that
- * starts no valid sequence stays as it is, and each malformed UTF-8 part, or
- * lone surrogate half, becomes U+FFFD.
- *
- * @param text - the encoded name or value
- * @returns the decoded text
- */
 export const decodeQueryComponent = (text) => toWellFormed(text).replace(/\+/g, ' ').replace(percentEncodedRun, decodePercentRun);
-/**
- * Lists the parameters of a query, decoded and in order.
- *
- * @param query - a query, with or without its leading `?`
- * @returns each parameter's name and value; a parameter with no `=` has an empty value
- */
 export const parseQuery = (query) => query
     .replace(/^\?/, '')
     .split('&')
@@ -156,36 +76,14 @@ export const parseQuery = (query) => query
     const value = equalsAt === -1 ? '' : part.slice(equalsAt + 1);
     return [decodeQueryComponent(name), decodeQueryComponent(value)];
 });
-/**
- * Turns query parameters into ordered pairs.
- *
- * @param parameters - a record or pairs; see {@link QueryParameters}
- * @returns the pairs, with every `undefined` record value left out
- */
 const toEntries = (parameters) => {
     if (Array.isArray(parameters))
         return parameters;
     return Object.entries(parameters).filter((entry) => entry[1] !== undefined);
 };
-/**
- * Writes a query, as `new URLSearchParams(parameters).toString()` does.
- *
- * @param parameters - a record or pairs; see {@link QueryParameters}
- * @returns the encoded query, with no leading `?`; empty for no parameters
- */
 export const buildQuery = (parameters) => toEntries(parameters)
     .map(([name, value]) => `${encodeQueryComponent(name)}=${encodeQueryComponent(value)}`)
     .join('&');
-/**
- * Sets one parameter in a query, as `URLSearchParams.set` does: the first
- * parameter of that name takes the value and any later ones are removed, or
- * the parameter is appended when none has the name.
- *
- * @param query - an encoded query, with or without its leading `?`
- * @param name - the parameter's name
- * @param value - its value
- * @returns the encoded query, with no leading `?`
- */
 export const setQueryParameter = (query, name, value) => {
     const entries = parseQuery(query);
     const firstAt = entries.findIndex(([entryName]) => entryName === name);
@@ -197,12 +95,6 @@ export const setQueryParameter = (query, name, value) => {
         return entry[0] === name ? [] : [entry];
     }));
 };
-/**
- * Splits an address at its first `#` and then at its first `?`.
- *
- * @param address - any address
- * @returns everything before the query, the query and the fragment, each without its delimiter
- */
 const splitAtQuery = (address) => {
     const fragmentAt = address.indexOf('#');
     const beforeFragment = fragmentAt === -1 ? address : address.slice(0, fragmentAt);
@@ -212,15 +104,6 @@ const splitAtQuery = (address) => {
         return { beforeQuery: beforeFragment, query: '', fragment };
     return { beforeQuery: beforeFragment.slice(0, queryAt), query: beforeFragment.slice(queryAt + 1), fragment };
 };
-/**
- * Adds query parameters to an address, as `url.searchParams.set` does for
- * each one in turn. A query already on the address is kept, and a fragment
- * stays at the end.
- *
- * @param address - the address, with or without a query
- * @param parameters - a record or pairs; see {@link QueryParameters}
- * @returns the address with the parameters set; the address unchanged when there are none
- */
 export const buildUrl = (address, parameters) => {
     const entries = toEntries(parameters);
     if (entries.length === 0)
@@ -229,15 +112,6 @@ export const buildUrl = (address, parameters) => {
     const updated = entries.reduce((current, [name, value]) => setQueryParameter(current, name, value), query);
     return `${beforeQuery}?${updated}${fragment === '' ? '' : `#${fragment}`}`;
 };
-/**
- * Reads the host the WHATWG `URL` reports from an authority: lowercase, with
- * any user name and password dropped, and the port dropped when it is the
- * scheme's default.
- *
- * @param authority - the text between `//` and the path
- * @param scheme - the lowercase scheme
- * @returns the host
- */
 const hostOfAuthority = (authority, scheme) => {
     const hostAndPort = authority.slice(authority.lastIndexOf('@') + 1).toLowerCase();
     const port = /:(\d*)$/.exec(hostAndPort);
@@ -249,12 +123,6 @@ const hostOfAuthority = (authority, scheme) => {
     const portNumber = String(Number(port[1]));
     return portNumber === defaultPorts[scheme] ? hostname : `${hostname}:${portNumber}`;
 };
-/**
- * Splits an address into its parts, without the WHATWG `URL` class.
- *
- * @param address - any address; leading and trailing spaces and control characters are ignored, as the WHATWG parser ignores them
- * @returns the parts; see {@link UrlParts}
- */
 export const splitUrl = (address) => {
     const trimmed = address.replace(/^[\u0000- ]+|[\u0000- ]+$/g, '');
     const { beforeQuery, query, fragment } = splitAtQuery(trimmed);
@@ -268,13 +136,6 @@ export const splitUrl = (address) => {
     const path = pathAt === -1 ? '/' : rest.slice(pathAt);
     return { scheme, host: hostOfAuthority(authority, scheme), path, query, fragment };
 };
-/**
- * Says whether a value is an absolute `http:` or `https:` address with a host.
- * It reads the scheme by its prefix, so it needs no `URL` class.
- *
- * @param value - any string
- * @returns true for an absolute `http:` or `https:` address
- */
 export const isHttpUrl = (value) => {
     const { scheme, host } = splitUrl(value);
     return (scheme === 'http' || scheme === 'https') && host !== '';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gibs/common",
-  "version": "1.18.0",
+  "version": "1.20.0",
   "description": "Low-level blockchain helpers shared across the Gibs Finance packages: caching, multicall, and serialization.",
   "keywords": [
     "ethereum",