@lodestar/utils 1.35.0-dev.f80d2d52da → 1.35.0-dev.fcf8d024ea

package/src/err.ts

@@ -0,0 +1,105 @@
+const symErr = Symbol("err");
+
+export type Err<T> = {[symErr]: true; error: T};
+
+export type Result<T, E> = T | Err<E>;
+
+export function Err<T>(error: T): Err<T> {
+  return {[symErr]: true, error};
+}
+
+/**
+ * Typeguard for Err<T>. Allows the pattern
+ * ```ts
+ * function getNumSquare(): Result<number, Error> {
+ *   const value = getNum();
+ *   if (isErr(value)) {
+ *     return value; // return as error
+ *   }
+ *   return value ** 2;
+ * }
+ * function getNum(): Result<number, Error>
+ * ```
+ * Since the non-error is not wrapped, it uses a symbol to prevent collisions
+ */
+export function isErr<T, E>(result: Result<T, E>): result is Err<E> {
+  return result !== null && typeof result === "object" && (result as Err<E>)[symErr] === true;
+}
+
+/**
+ * Given an array of results, run a function only on an array of ok results.
+ * Returns a new array of results with same length as `results` where the ok
+ * value may be Err or T2.
+ */
+export function mapOkResults<T1, T2, E>(
+  results: Result<T1, E>[],
+  fn: (items: T1[]) => Result<T2, E>[]
+): Result<T2, E>[] {
+  const oks: T1[] = [];
+
+  for (let i = 0; i < results.length; i++) {
+    const result = results[i];
+
+    if (!isErr(result)) {
+      oks.push(result);
+    }
+  }
+
+  const outOksResults = fn(oks);
+  if (outOksResults.length !== oks.length) {
+    throw Error("mapOkResults fn must return same length");
+  }
+
+  const outResults: Result<T2, E>[] = [];
+
+  for (let i = 0, j = 0; i < results.length; i++) {
+    const result = results[i];
+
+    if (isErr(result)) {
+      outResults.push(result);
+    } else {
+      outResults.push(outOksResults[j]);
+      j++;
+    }
+  }
+
+  return outResults;
+}
+
+/**
+ * See {@link mapOkResults} but `fn` is async
+ */
+export async function mapOkResultsAsync<T1, T2, E>(
+  results: Result<T1, E>[],
+  fn: (items: T1[]) => Promise<Result<T2, E>[]>
+): Promise<Result<T2, E>[]> {
+  const oks: T1[] = [];
+
+  for (let i = 0; i < results.length; i++) {
+    const result = results[i];
+
+    if (!isErr(result)) {
+      oks.push(result);
+    }
+  }
+
+  const outOksResults = await fn(oks);
+  if (outOksResults.length !== oks.length) {
+    throw Error("mapOkResults fn must return same length");
+  }
+
+  const outResults: Result<T2, E>[] = [];
+
+  for (let i = 0, j = 0; i < results.length; i++) {
+    const result = results[i];
+
+    if (isErr(result)) {
+      outResults.push(result);
+    } else {
+      outResults.push(outOksResults[j]);
+      j++;
+    }
+  }
+
+  return outResults;
+}

package/src/errors.ts

@@ -0,0 +1,73 @@
+export type LodestarErrorMetaData = Record<string, string | number | null>;
+export type LodestarErrorObject = {
+  message: string;
+  stack: string;
+  className: string;
+  type: LodestarErrorMetaData;
+};
+export type FromObjectFn = (object: LodestarErrorObject) => Error;
+
+/**
+ * Generic Lodestar error with attached metadata
+ */
+export class LodestarError<T extends {code: string}> extends Error {
+  type: T;
+  constructor(type: T, message?: string, stack?: string) {
+    super(message || type.code);
+    this.type = type;
+    if (stack) this.stack = stack;
+  }
+
+  getMetadata(): LodestarErrorMetaData {
+    return this.type;
+  }
+
+  /**
+   * Get the metadata and the stacktrace for the error.
+   */
+  toObject(): LodestarErrorObject {
+    return {
+      type: this.getMetadata(),
+      message: this.message ?? "",
+      stack: this.stack ?? "",
+      className: this.constructor.name,
+    };
+  }
+
+  static fromObject(obj: LodestarErrorObject): LodestarError<{code: string}> {
+    return new LodestarError(obj.type as {code: string}, obj.message, obj.stack);
+  }
+}
+
+/**
+ * Throw this error when an upstream abort signal aborts
+ */
+export class ErrorAborted extends Error {
+  constructor(message?: string) {
+    super(`Aborted ${message || ""}`);
+  }
+}
+
+/**
+ * Throw this error when wrapped timeout expires
+ */
+export class TimeoutError extends Error {
+  constructor(message?: string) {
+    super(`Timeout ${message || ""}`);
+  }
+}
+
+/**
+ * Returns true if arg `e` is an instance of `ErrorAborted`
+ */
+export function isErrorAborted(e: unknown): e is ErrorAborted {
+  return e instanceof ErrorAborted;
+}
+
+/**
+ * Extend an existing error by appending a string to its `e.message`
+ */
+export function extendError(e: Error, appendMessage: string): Error {
+  e.message = `${e.message} - ${appendMessage}`;
+  return e;
+}

package/src/ethConversion.ts

@@ -0,0 +1,12 @@
+export const ETH_TO_GWEI = BigInt(10 ** 9);
+export const GWEI_TO_WEI = BigInt(10 ** 9);
+export const ETH_TO_WEI = ETH_TO_GWEI * GWEI_TO_WEI;
+
+type EthNumeric = bigint;
+
+/**
+ * Convert gwei to wei.
+ */
+export function gweiToWei(gwei: EthNumeric): EthNumeric {
+  return gwei * GWEI_TO_WEI;
+}

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;
+}