@lodestar/utils 1.35.0-dev.8ea34e52ba → 1.35.0-dev.901d719660

package/src/fetch.ts

@@ -0,0 +1,188 @@
+/**
+ * Native fetch with transparent and consistent error handling
+ *
+ * [MDN Reference](https://developer.mozilla.org/docs/Web/API/fetch)
+ */
+async function wrappedFetch(url: string | URL, init?: RequestInit): Promise<Response> {
+  try {
+    // This function wraps global `fetch` which should only be directly called here
+    // biome-ignore lint/style/noRestrictedGlobals: We need to use global `fetch`
+    return await fetch(url, init);
+  } catch (e) {
+    throw new FetchError(url, e);
+  }
+}
+
+export {wrappedFetch as fetch};
+
+export function isFetchError(e: unknown): e is FetchError {
+  return e instanceof FetchError;
+}
+
+export type FetchErrorType = "failed" | "input" | "aborted" | "timeout" | "unknown";
+
+type FetchErrorCause = NativeFetchFailedError["cause"] | NativeFetchInputError["cause"];
+
+export class FetchError extends Error {
+  type: FetchErrorType;
+  code: string;
+  cause?: FetchErrorCause;
+
+  constructor(url: string | URL, e: unknown) {
+    if (isNativeFetchFailedError(e)) {
+      super(`Request to ${url.toString()} failed, reason: ${e.cause.message}`);
+      this.type = "failed";
+      this.code = e.cause.code || "ERR_FETCH_FAILED";
+      this.cause = e.cause;
+    } else if (isNativeFetchInputError(e)) {
+      // For input errors the e.message is more detailed
+      super(e.message);
+      this.type = "input";
+      this.code = e.cause.code || "ERR_INVALID_INPUT";
+      this.cause = e.cause;
+    } else if (isNativeFetchAbortError(e)) {
+      super(`Request to ${url.toString()} was aborted`);
+      this.type = "aborted";
+      this.code = "ERR_ABORTED";
+    } else if (isNativeFetchTimeoutError(e)) {
+      super(`Request to ${url.toString()} timed out`);
+      this.type = "timeout";
+      this.code = "ERR_TIMEOUT";
+    }
+    // There are few incompatibilities related to `fetch` with NodeJS
+    // So we have to wrap those cases here explicitly
+    // https://github.com/oven-sh/bun/issues/20486
+    else if (isBunError(e) && e.code === "ConnectionRefused") {
+      super("TypeError: fetch failed");
+      this.type = "failed";
+      this.code = "ENOTFOUND";
+      this.cause = e as unknown as FetchErrorCause;
+    } else if (isBunError(e) && e.code === "ECONNRESET") {
+      super("TypeError: fetch failed");
+      this.type = "failed";
+      this.code = "UND_ERR_SOCKET";
+      this.cause = e as unknown as FetchErrorCause;
+    } else if (isBun && (e as Error).message.includes("protocol must be")) {
+      super("fetch failed");
+      this.type = "failed";
+      this.code = "ERR_FETCH_FAILED";
+      this.cause = e as unknown as FetchErrorCause;
+    } else if ((e as Error).message.includes("URL is invalid")) {
+      super("Failed to parse URL from invalid-url");
+      this.type = "input";
+      this.code = "ERR_INVALID_URL";
+      this.cause = e as unknown as FetchErrorCause;
+    } else {
+      super((e as Error).message);
+      this.type = "unknown";
+      this.code = "ERR_UNKNOWN";
+    }
+    this.name = this.constructor.name;
+  }
+}
+
+type NativeFetchError = TypeError & {
+  cause: Error & {
+    code?: string;
+  };
+};
+
+/**
+ * ```
+ * TypeError: fetch failed
+ *   cause: Error: connect ECONNREFUSED 127.0.0.1:9596
+ *     errno: -111,
+ *     code: 'ECONNREFUSED',
+ *     syscall: 'connect',
+ *     address: '127.0.0.1',
+ *     port: 9596
+ * ---------------------------
+ * TypeError: fetch failed
+ *   cause: Error: getaddrinfo ENOTFOUND non-existent-domain
+ *     errno: -3008,
+ *     code: 'ENOTFOUND',
+ *     syscall: 'getaddrinfo',
+ *     hostname: 'non-existent-domain'
+ * ---------------------------
+ * TypeError: fetch failed
+ *   cause: SocketError: other side closed
+ *     code: 'UND_ERR_SOCKET',
+ *     socket: {}
+ * ---------------------------
+ * TypeError: fetch failed
+ *   cause: Error: unknown scheme
+ *     [cause]: undefined
+ * ```
+ */
+type NativeFetchFailedError = NativeFetchError & {
+  message: "fetch failed";
+  cause: {
+    errno?: string;
+    syscall?: string;
+    address?: string;
+    port?: string;
+    hostname?: string;
+    socket?: object;
+    [prop: string]: unknown;
+  };
+};
+
+/**
+ * ```
+ * TypeError: Failed to parse URL from invalid-url
+ *   [cause]: TypeError [ERR_INVALID_URL]: Invalid URL
+ *     input: 'invalid-url',
+ *     code: 'ERR_INVALID_URL'
+ * ```
+ */
+type NativeFetchInputError = NativeFetchError & {
+  cause: {
+    input: unknown;
+  };
+};
+
+/**
+ * ```
+ * DOMException [AbortError]: This operation was aborted
+ * ```
+ */
+type NativeFetchAbortError = DOMException & {
+  name: "AbortError";
+};
+
+/**
+ * ```
+ * DOMException [TimeoutError]: The operation was aborted due to timeout
+ * ```
+ */
+type NativeFetchTimeoutError = DOMException & {
+  name: "TimeoutError";
+};
+
+function isNativeFetchError(e: unknown): e is NativeFetchError {
+  return e instanceof TypeError && (e as NativeFetchError).cause instanceof Error;
+}
+
+function isNativeFetchFailedError(e: unknown): e is NativeFetchFailedError {
+  return isNativeFetchError(e) && (e as NativeFetchFailedError).message === "fetch failed";
+}
+
+function isNativeFetchInputError(e: unknown): e is NativeFetchInputError {
+  return isNativeFetchError(e) && (e as NativeFetchInputError).cause.input !== undefined;
+}
+
+function isNativeFetchAbortError(e: unknown): e is NativeFetchAbortError {
+  return e instanceof DOMException && (e as NativeFetchAbortError).name === "AbortError";
+}
+
+function isNativeFetchTimeoutError(e: unknown): e is NativeFetchTimeoutError {
+  return e instanceof DOMException && (e as NativeFetchTimeoutError).name === "TimeoutError";
+}
+
+const isBun = "bun" in process.versions;
+
+type BunError = {code: string; path: string; errno: number; message: string};
+
+function isBunError(e: unknown): e is BunError {
+  return isBun && typeof e === "object" && e !== null && "code" in e && "path" in e && "errno" in e && "message" in e;
+}

package/src/format.ts

@@ -0,0 +1,119 @@
+import {toRootHex} from "./bytes/index.js";
+import {ETH_TO_WEI} from "./ethConversion.js";
+
+/**
+ * Format bytes as `0x1234…1234`
+ * 4 bytes can represent 4294967296 values, so the chance of collision is low
+ */
+export function prettyBytes(root: Uint8Array | string): string {
+  const str = typeof root === "string" ? root : toRootHex(root);
+  return `${str.slice(0, 6)}…${str.slice(-4)}`;
+}
+
+/**
+ * Format bytes as `0x1234…`
+ * Paired with block numbers or slots, it can still act as a decent identify-able format
+ */
+export function prettyBytesShort(root: Uint8Array | string): string {
+  const str = typeof root === "string" ? root : toRootHex(root);
+  return `${str.slice(0, 6)}…`;
+}
+
+/**
+ * Truncate and format bytes as `0x123456789abc`
+ * 6 bytes is sufficient to avoid collisions and it allows to easily look up
+ * values on explorers like beaconcha.in while improving readability of logs
+ */
+export function truncBytes(root: Uint8Array | string): string {
+  const str = typeof root === "string" ? root : toRootHex(root);
+  return str.slice(0, 14);
+}
+
+/**
+ * Format a bigint value as a decimal string
+ */
+export function formatBigDecimal(numerator: bigint, denominator: bigint, maxDecimalFactor: bigint): string {
+  const full = numerator / denominator;
+  const fraction = ((numerator - full * denominator) * maxDecimalFactor) / denominator;
+
+  // zeros to be added post decimal are number of zeros in maxDecimalFactor - number of digits in fraction
+  const zerosPostDecimal = String(maxDecimalFactor).length - 1 - String(fraction).length;
+  return `${full}.${"0".repeat(zerosPostDecimal)}${fraction}`;
+}
+
+// display upto 5 decimal places
+const MAX_DECIMAL_FACTOR = BigInt("100000");
+
+/**
+ * Format wei as ETH, with up to 5 decimals
+ */
+export function formatWeiToEth(wei: bigint): string {
+  return formatBigDecimal(wei, ETH_TO_WEI, MAX_DECIMAL_FACTOR);
+}
+
+/**
+ * Format wei as ETH, with up to 5 decimals and append ' ETH'
+ */
+export function prettyWeiToEth(wei: bigint): string {
+  return `${formatWeiToEth(wei)} ETH`;
+}
+
+/**
+ * Format milliseconds to time format HH:MM:SS.ms
+ */
+export function prettyMsToTime(timeMs: number): string {
+  const date = new Date(0, 0, 0, 0, 0, 0, timeMs);
+  return `${date.getHours()}:${date.getMinutes()}:${date.getSeconds()}.${date.getMilliseconds()}`;
+}
+
+/**
+ * Remove 0x prefix from a string
+ */
+export function strip0xPrefix(hex: string): string {
+  return hex.startsWith("0x") ? hex.slice(2) : hex;
+}
+
+export function groupSequentialIndices(indices: number[]): string[] {
+  if (indices.length === 0) {
+    return [];
+  }
+
+  // Get unique values and sort them
+  const uniqueValues = Array.from(new Set(indices)).sort((a, b) => a - b);
+
+  const result: string[] = [];
+  let start = uniqueValues[0];
+  let end = uniqueValues[0];
+
+  for (let i = 1; i < uniqueValues.length; i++) {
+    const current = uniqueValues[i];
+
+    if (current === end + 1) {
+      end = current; // extend the range
+    } else {
+      result.push(start === end ? `${start}` : `${start}-${end}`);
+      start = current;
+      end = current;
+    }
+  }
+
+  // Push the last range
+  result.push(start === end ? `${start}` : `${start}-${end}`);
+
+  return result;
+}
+
+/**
+ * Pretty print indices from an array of numbers.
+ *
+ * example:
+ * ```ts
+ * const indices = [1, 3, 109, 110, 111, 112, 113, 127];
+ * console.log(prettyPrintIndices(indices));
+ * // `1,3,110-113,127`
+ * ```
+ */
+export function prettyPrintIndices(indices: number[]): string {
+  const increments = groupSequentialIndices(indices);
+  return `[${increments.join(", ")}]`;
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+export * from "./assert.js";
+export * from "./base64.js";
+export * from "./bytes/index.js";
+export * from "./bytes.js";
+export * from "./command.js";
+export * from "./diff.js";
+export * from "./err.js";
+export * from "./errors.js";
+export * from "./ethConversion.js";
+export * from "./fetch.js";
+export * from "./format.js";
+export * from "./iterator.js";
+export * from "./logger.js";
+export * from "./map.js";
+export * from "./math.js";
+export * from "./metrics.js";
+export * from "./notNullish.js";
+export * from "./objects.js";
+export * from "./promise.js";
+export {type RetryOptions, retry} from "./retry.js";
+export * from "./sleep.js";
+export * from "./sort.js";
+export * from "./timeout.js";
+export {type RecursivePartial, type RequiredSelective, bnToNum} from "./types.js";
+export * from "./url.js";
+export * from "./verifyMerkleBranch.js";
+export * from "./waitFor.js";
+export * from "./yaml/index.js";

package/src/iterator.ts

@@ -0,0 +1,10 @@
+// ES2024 onward we have Array.fromAsync which does exactly this
+// This function is here as wrapper to be deleted later when we upgrade
+// minimum nodejs requirement to > 22
+export async function fromAsync<T>(iter: AsyncIterable<T>): Promise<T[]> {
+  const arr: T[] = [];
+  for await (const v of iter) {
+    arr.push(v);
+  }
+  return arr;
+}

package/src/logger.ts

@@ -0,0 +1,20 @@
+/**
+ * Interface of a generic Lodestar logger. For implementations, see `@lodestar/logger`
+ */
+export type Logger = Record<Exclude<LogLevel, LogLevel.trace>, LogHandler>;
+
+export enum LogLevel {
+  error = "error",
+  warn = "warn",
+  info = "info",
+  verbose = "verbose",
+  debug = "debug",
+  trace = "trace",
+}
+
+export const LogLevels = Object.values(LogLevel);
+
+export type LogHandler = (message: string, context?: LogData, error?: Error) => void;
+
+export type LogDataBasic = string | number | bigint | boolean | null | undefined;
+export type LogData = LogDataBasic | Record<string, LogDataBasic> | LogDataBasic[] | Record<string, LogDataBasic>[];

package/src/map.ts

@@ -0,0 +1,108 @@
+export class MapDef<K, V> extends Map<K, V> {
+  constructor(private readonly getDefault: () => V) {
+    super();
+  }
+
+  getOrDefault(key: K): V {
+    let value = super.get(key);
+    if (value === undefined) {
+      value = this.getDefault();
+      this.set(key, value);
+    }
+    return value;
+  }
+}
+
+/**
+ * Extends MapDef but ensures that there always a max of `maxKeys` keys
+ */
+export class MapDefMax<K, V> {
+  private readonly map = new Map<K, V>();
+
+  constructor(
+    private readonly getDefault: () => V,
+    private readonly maxKeys: number
+  ) {}
+
+  getOrDefault(key: K): V {
+    let value = this.map.get(key);
+    if (value === undefined) {
+      value = this.getDefault();
+      this.map.set(key, value);
+      pruneSetToMax(this.map, this.maxKeys);
+    }
+    return value;
+  }
+
+  get(key: K): V | undefined {
+    return this.map.get(key);
+  }
+}
+
+/**
+ * 2 dimensions Es6 Map
+ */
+export class Map2d<K1, K2, V> {
+  readonly map = new Map<K1, Map<K2, V>>();
+
+  get(k1: K1, k2: K2): V | undefined {
+    return this.map.get(k1)?.get(k2);
+  }
+
+  set(k1: K1, k2: K2, v: V): void {
+    let map2 = this.map.get(k1);
+    if (!map2) {
+      map2 = new Map<K2, V>();
+      this.map.set(k1, map2);
+    }
+    map2.set(k2, v);
+  }
+}
+
+/**
+ * 2 dimensions Es6 Map + regular array
+ */
+export class Map2dArr<K1, V> {
+  readonly map = new Map<K1, V[]>();
+
+  get(k1: K1, idx: number): V | undefined {
+    return this.map.get(k1)?.[idx];
+  }
+
+  set(k1: K1, idx: number, v: V): void {
+    let arr = this.map.get(k1);
+    if (!arr) {
+      arr = [];
+      this.map.set(k1, arr);
+    }
+    arr[idx] = v;
+  }
+}
+
+/**
+ * Prune an arbitrary set removing the first keys to have a set.size === maxItems.
+ * Returns the count of deleted items.
+ *
+ * Keys can be sorted by `compareFn` to get more control over which items to prune first
+ */
+export function pruneSetToMax<T>(
+  set: Set<T> | Map<T, unknown>,
+  maxItems: number,
+  compareFn?: (a: T, b: T) => number
+): number {
+  let itemsToDelete = set.size - maxItems;
+  const deletedItems = Math.max(0, itemsToDelete);
+
+  if (itemsToDelete > 0) {
+    const keys = compareFn ? Array.from(set.keys()).sort(compareFn) : set.keys();
+    for (const key of keys) {
+      set.delete(key);
+      itemsToDelete--;
+      if (itemsToDelete <= 0) {
+        break;
+      }
+    }
+  }
+
+  return deletedItems;
+}

package/src/math.ts

@@ -0,0 +1,55 @@
+/**
+ * Return the min number between two big numbers.
+ */
+export function bigIntMin(a: bigint, b: bigint): bigint {
+  return a < b ? a : b;
+}
+
+/**
+ * Return the max number between two big numbers.
+ */
+export function bigIntMax(a: bigint, b: bigint): bigint {
+  return a > b ? a : b;
+}
+
+export function intDiv(dividend: number, divisor: number): number {
+  return Math.floor(dividend / divisor);
+}
+
+/**
+ * Calculate the largest integer k such that k**2 <= n.
+ */
+export function intSqrt(n: number): number {
+  let x = n;
+  let y = intDiv(x + 1, 2);
+  while (y < x) {
+    x = y;
+    y = intDiv(x + intDiv(n, x), 2);
+  }
+  return x;
+}
+
+export function bigIntSqrt(n: bigint): bigint {
+  let x = n;
+  let y = (x + BigInt(1)) / BigInt(2);
+  while (y < x) {
+    x = y;
+    y = (x + n / x) / BigInt(2);
+  }
+  return x;
+}
+
+/**
+ * Regenerates a random integer between min (included) and max (excluded).
+ */
+export function randBetween(min: number, max: number): number {
+  return Math.floor(Math.random() * (max - min)) + min;
+}
+
+/**
+ * Wraps randBetween and returns a bigNumber.
+ * @returns {bigint}
+ */
+export function randBetweenBigInt(min: number, max: number): bigint {
+  return BigInt(randBetween(min, max));
+}

package/src/metrics.ts

@@ -0,0 +1,73 @@
+import {NonEmptyArray} from "./types.js";
+
+export type NoLabels = Record<string, never>;
+export type LabelsGeneric = Record<string, string | number>;
+export type LabelKeys<Labels extends LabelsGeneric> = Extract<keyof Labels, string>;
+export type CollectFn<Labels extends LabelsGeneric> = (metric: Gauge<Labels>) => void;
+
+export interface Gauge<Labels extends LabelsGeneric = NoLabels> {
+  inc: NoLabels extends Labels ? (value?: number) => void : (labels: Labels, value?: number) => void;
+  dec: NoLabels extends Labels ? (value?: number) => void : (labels: Labels, value?: number) => void;
+  set: NoLabels extends Labels ? (value: number) => void : (labels: Labels, value: number) => void;
+
+  collect?(): void;
+}
+
+export interface GaugeExtra<Labels extends LabelsGeneric = NoLabels> extends Omit<Gauge<Labels>, "collect"> {
+  addCollect(collectFn: CollectFn<Labels>): void;
+}
+
+export interface Histogram<Labels extends LabelsGeneric = NoLabels> {
+  startTimer(): NoLabels extends Labels ? () => number : (labels: Labels) => number;
+  startTimer<L extends Partial<Labels>>(
+    labels?: NoLabels extends Labels ? never : L
+  ): keyof Omit<Labels, keyof L> extends never ? () => number : (labels: Omit<Labels, keyof L>) => number;
+
+  observe: NoLabels extends Labels ? (value: number) => void : (labels: Labels, value: number) => void;
+
+  reset(): void;
+}
+
+export interface AvgMinMax<Labels extends LabelsGeneric = NoLabels> {
+  addGetValuesFn(getValuesFn: () => number[]): void;
+
+  set: NoLabels extends Labels ? (values: number[]) => void : (labels: Labels, values: number[]) => void;
+}
+
+export interface Counter<Labels extends LabelsGeneric = NoLabels> {
+  inc: NoLabels extends Labels ? (value?: number) => void : (labels: Labels, value?: number) => void;
+}
+
+export type GaugeConfig<Labels extends LabelsGeneric> = {
+  name: string;
+  help: string;
+} & (NoLabels extends Labels ? {labelNames?: never} : {labelNames: NonEmptyArray<LabelKeys<Labels>>});
+
+export type HistogramConfig<Labels extends LabelsGeneric> = GaugeConfig<Labels> & {
+  buckets: number[];
+};
+
+export type AvgMinMaxConfig<Labels extends LabelsGeneric> = GaugeConfig<Labels>;
+
+export type CounterConfig<Labels extends LabelsGeneric> = GaugeConfig<Labels>;
+
+export type StaticConfig<Labels extends LabelsGeneric> = {
+  name: GaugeConfig<Labels>["name"];
+  help: GaugeConfig<Labels>["help"];
+  value: Record<LabelKeys<Labels>, string>;
+};
+
+export interface MetricsRegister {
+  gauge<Labels extends LabelsGeneric = NoLabels>(config: GaugeConfig<Labels>): Gauge<Labels>;
+  histogram<Labels extends LabelsGeneric = NoLabels>(config: HistogramConfig<Labels>): Histogram<Labels>;
+  counter<Labels extends LabelsGeneric = NoLabels>(config: CounterConfig<Labels>): Counter<Labels>;
+}
+
+export interface MetricsRegisterExtra extends MetricsRegister {
+  gauge<Labels extends LabelsGeneric = NoLabels>(config: GaugeConfig<Labels>): GaugeExtra<Labels>;
+}
+
+export interface MetricsRegisterCustom extends MetricsRegisterExtra {
+  avgMinMax<Labels extends LabelsGeneric = NoLabels>(config: AvgMinMaxConfig<Labels>): AvgMinMax<Labels>;
+  static<Labels extends LabelsGeneric = NoLabels>(config: StaticConfig<Labels>): void;
+}

package/src/notNullish.ts

@@ -0,0 +1,11 @@
+/**
+ * Type-safe helper to filter out nullist values from an array
+ * ```js
+ * const array: (string | null)[] = ['foo', null];
+ * const filteredArray: string[] = array.filter(notEmpty);
+ * ```
+ * @param value
+ */
+export function notNullish<TValue>(value: TValue | null | undefined): value is TValue {
+  return value !== null && value !== undefined;
+}