@lodestar/utils 1.35.0-dev.e18102ed8c → 1.35.0-dev.f2a741bbe4

package/src/command.ts

@@ -0,0 +1,74 @@
+import type {Argv, Options} from "yargs";
+
+export interface CliExample {
+  command: string;
+  title?: string;
+  description?: string;
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: We need to use `any` type here
+export interface CliOptionDefinition<T = any> extends Options {
+  example?: Omit<CliExample, "title">;
+  // Ensure `type` property matches type of `T`
+  type: T extends string
+    ? "string"
+    : T extends number
+      ? "number"
+      : T extends boolean
+        ? "boolean"
+        : T extends Array<unknown>
+          ? "array"
+          : never;
+}
+
+export type CliCommandOptions<OwnArgs> = Required<{
+  [K in keyof OwnArgs]: undefined extends OwnArgs[K]
+    ? CliOptionDefinition<OwnArgs[K]>
+    : // If arg cannot be undefined it must specify a default value or be provided by the user
+      CliOptionDefinition<OwnArgs[K]> & (Required<Pick<Options, "default">> | {demandOption: true});
+}>;
+
+// biome-ignore lint/suspicious/noExplicitAny: We need to use `any` type here
+export interface CliCommand<OwnArgs = Record<never, never>, ParentArgs = Record<never, never>, R = any> {
+  command: string;
+  describe: string;
+  /**
+   * The folder in docs/pages that the cli.md should be placed in.  If not provided no
+   * cli flags page will be generated for the command
+   */
+  docsFolder?: string;
+  examples?: CliExample[];
+  options?: CliCommandOptions<OwnArgs>;
+  // 1st arg: any = free own sub command options
+  // 2nd arg: subcommand parent options is = to this command options + parent options
+  // biome-ignore lint/suspicious/noExplicitAny: We need to use `any` type here
+  subcommands?: CliCommand<any, OwnArgs & ParentArgs>[];
+  handler?: (args: OwnArgs & ParentArgs) => Promise<R>;
+}
+
+/**
+ * Register a CliCommand type to yargs. Recursively registers subcommands too.
+ * @param yargs
+ * @param cliCommand
+ */
+
+// biome-ignore lint/suspicious/noExplicitAny: We need to use `any` type here
+export function registerCommandToYargs(yargs: Argv, cliCommand: CliCommand<any, any>): void {
+  yargs.command({
+    command: cliCommand.command,
+    describe: cliCommand.describe,
+    builder: (yargsBuilder) => {
+      yargsBuilder.options(cliCommand.options ?? {});
+      for (const subcommand of cliCommand.subcommands ?? []) {
+        registerCommandToYargs(yargsBuilder, subcommand);
+      }
+      if (cliCommand.examples) {
+        for (const example of cliCommand.examples) {
+          yargsBuilder.example(`$0 ${example.command}`, example.description ?? "");
+        }
+      }
+      return yargs;
+    },
+    handler: cliCommand.handler ?? function emptyHandler(): void {},
+  });
+}

package/src/diff.ts

@@ -0,0 +1,234 @@
+import fs from "node:fs";
+
+const primitiveTypeof = ["number", "string", "bigint", "boolean"];
+export type BufferType = Uint8Array | Uint32Array;
+export type PrimitiveType = number | string | bigint | boolean | BufferType;
+export type DiffableCollection = Record<string | number, PrimitiveType>;
+export type Diffable = PrimitiveType | Array<PrimitiveType> | DiffableCollection;
+
+export interface Diff {
+  objectPath: string;
+  errorMessage?: string;
+  val1: Diffable;
+  val2: Diffable;
+}
+
+export function diffUint8Array(val1: Uint8Array, val2: PrimitiveType, objectPath: string): Diff[] {
+  if (!(val2 instanceof Uint8Array)) {
+    return [
+      {
+        objectPath,
+        errorMessage: `val1${objectPath} is a Uint8Array, but val2${objectPath} is not`,
+        val1,
+        val2,
+      },
+    ];
+  }
+  const hex1 = Buffer.from(val1).toString("hex");
+  const hex2 = Buffer.from(val2).toString("hex");
+  if (hex1 !== hex2) {
+    return [
+      {
+        objectPath,
+        val1: `0x${hex1}`,
+        val2: `0x${hex2}`,
+      },
+    ];
+  }
+  return [];
+}
+
+export function diffUint32Array(val1: Uint32Array, val2: PrimitiveType, objectPath: string): Diff[] {
+  if (!(val2 instanceof Uint32Array)) {
+    return [
+      {
+        objectPath,
+        errorMessage: `val1${objectPath} is a Uint32Array, but val2${objectPath} is not`,
+        val1,
+        val2,
+      },
+    ];
+  }
+  const diffs: Diff[] = [];
+  val1.forEach((value, index) => {
+    const value2 = val2[index];
+    if (value !== value2) {
+      diffs.push({
+        objectPath: `${objectPath}[${index}]`,
+        val1: `0x${value.toString(16).padStart(8, "0")}`,
+        val2: value2 ? `0x${val2[index].toString(16).padStart(8, "0")}` : "undefined",
+      });
+    }
+  });
+  return diffs;
+}
+
+function diffPrimitiveValue(val1: PrimitiveType, val2: PrimitiveType, objectPath: string): Diff[] {
+  if (val1 instanceof Uint8Array) {
+    return diffUint8Array(val1, val2, objectPath);
+  }
+  if (val1 instanceof Uint32Array) {
+    return diffUint32Array(val1, val2, objectPath);
+  }
+
+  const diff = {objectPath, val1, val2} as Diff;
+  const type1 = typeof val1;
+  if (!primitiveTypeof.includes(type1)) {
+    diff.errorMessage = `val1${objectPath} is not a supported type`;
+  }
+  const type2 = typeof val2;
+  if (!primitiveTypeof.includes(type2)) {
+    diff.errorMessage = `val2${objectPath} is not a supported type`;
+  }
+  if (type1 !== type2) {
+    diff.errorMessage = `val1${objectPath} is not the same type as val2${objectPath}`;
+  }
+  if (val1 !== val2) {
+    return [diff];
+  }
+  return [];
+}
+
+function isPrimitiveValue(val: unknown): val is PrimitiveType {
+  if (Array.isArray(val)) return false;
+  if (typeof val === "object") {
+    return val instanceof Uint8Array || val instanceof Uint32Array;
+  }
+  return true;
+}
+
+function isDiffable(val: unknown): val is Diffable {
+  return !(typeof val === "function" || typeof val === "symbol" || typeof val === "undefined" || val === null);
+}
+
+export function getDiffs(val1: Diffable, val2: Diffable, objectPath: string): Diff[] {
+  if (isPrimitiveValue(val1)) {
+    if (!isPrimitiveValue(val2)) {
+      return [
+        {
+          objectPath,
+          errorMessage: `val1${objectPath} is a primitive value and val2${objectPath} is not`,
+          val1,
+          val2,
+        },
+      ];
+    }
+    return diffPrimitiveValue(val1, val2, objectPath);
+  }
+
+  const isArray = Array.isArray(val1);
+  let errorMessage: string | undefined;
+  if (isArray && !Array.isArray(val2)) {
+    errorMessage = `val1${objectPath} is an array and val2${objectPath} is not`;
+  } else if (typeof val1 === "object" && typeof val2 !== "object") {
+    errorMessage = `val1${objectPath} is a nested object and val2${objectPath} is not`;
+  }
+  if (errorMessage) {
+    return [
+      {
+        objectPath,
+        errorMessage,
+        val1,
+        val2,
+      },
+    ];
+  }
+
+  const diffs: Diff[] = [];
+  for (const [index, value] of Object.entries(val1)) {
+    if (!isDiffable(value)) {
+      diffs.push({objectPath, val1, val2, errorMessage: `val1${objectPath} is not Diffable`});
+      continue;
+    }
+    const value2 = (val2 as DiffableCollection)[index];
+    if (!isDiffable(value2)) {
+      diffs.push({objectPath, val1, val2, errorMessage: `val2${objectPath} is not Diffable`});
+      continue;
+    }
+    const innerPath = isArray ? `${objectPath}[${index}]` : `${objectPath}.${index}`;
+    diffs.push(...getDiffs(value, value2, innerPath));
+  }
+  return diffs;
+}
+
+/**
+ * Find the different values on complex, nested objects. Outputs the path through the object to
+ * each value that does not match from val1 and val2. Optionally can output the values that differ.
+ *
+ * For objects that differ greatly, can write to a file instead of the terminal for analysis
+ *
+ * ## Example
+ * ```ts
+ * const obj1 = {
+ *   key1: {
+ *     key2: [
+ *       { key3: 1 },
+ *       { key3: new Uint8Array([1, 2, 3]) }
+ *     ]
+ *   },
+ *   key4: new Uint32Array([1, 2, 3]),
+ *   key5: 362436
+ * };
+ *
+ * const obj2 = {
+ *   key1: {
+ *     key2: [
+ *       { key3: 1 },
+ *       { key3: new Uint8Array([1, 2, 4]) }
+ *     ]
+ *   },
+ *   key4: new Uint32Array([1, 2, 4])
+ *   key5: true
+ * };
+ *
+ * diffObjects(obj1, obj2, true);
+ *
+ *
+ * ```
+ *
+ * ## Output
+ * ```sh
+ * val.key1.key2[1].key3
+ *   - 0x010203
+ *   - 0x010204
+ * val.key4[2]
+ *   - 0x00000003
+ *   - 0x00000004
+ * val.key5
+ *   val1.key5 is not the same type as val2.key5
+ *   - 362436
+ *   - true
+ * ```
+ */
+export function diff(val1: unknown, val2: unknown, outputValues = false, filename?: string): void {
+  if (!isDiffable(val1)) {
+    // biome-ignore lint/suspicious/noConsole: We need to log to the console
+    console.log("val1 is not Diffable");
+    return;
+  }
+  if (!isDiffable(val2)) {
+    // biome-ignore lint/suspicious/noConsole: We need to log to the console
+    console.log("val2 is not Diffable");
+    return;
+  }
+  const diffs = getDiffs(val1, val2, "");
+  let output = "";
+  if (diffs.length) {
+    for (const diff of diffs) {
+      let diffOutput = `value${diff.objectPath}`;
+      if (diff.errorMessage) {
+        diffOutput += `\n  ${diff.errorMessage}`;
+      }
+      if (outputValues) {
+        diffOutput += `\n  - ${diff.val1.toString()}\n  - ${diff.val2.toString()}\n`;
+      }
+      output += `${diffOutput}\n`;
+    }
+    if (filename) {
+      fs.writeFileSync(filename, output);
+    } else {
+      // biome-ignore lint/suspicious/noConsole: We need to log to the console
+      console.log(output);
+    }
+  }
+}

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