@nomicfoundation/hardhat-utils 3.0.0-next.0

package/src/internal/request.ts

@@ -0,0 +1,165 @@
+import type { DispatcherOptions, RequestOptions } from "../request.js";
+import type EventEmitter from "node:events";
+import type UndiciT from "undici";
+
+import path from "node:path";
+
+import { mkdir } from "../fs.js";
+import { isObject } from "../lang.js";
+import {
+  ConnectionRefusedError,
+  DEFAULT_MAX_REDIRECTS,
+  DEFAULT_TIMEOUT_IN_MILLISECONDS,
+  DEFAULT_USER_AGENT,
+  getDispatcher,
+  RequestTimeoutError,
+  ResponseStatusCodeError,
+} from "../request.js";
+
+export async function generateTempFilePath(filePath: string): Promise<string> {
+  const { dir, ext, name } = path.parse(filePath);
+
+  await mkdir(dir);
+
+  return path.format({
+    dir,
+    ext,
+    name: `tmp-${name}`,
+  });
+}
+
+export async function getBaseRequestOptions(
+  requestUrl: string,
+  { extraHeaders, abortSignal, queryParams }: RequestOptions = {},
+  dispatcherOrDispatcherOptions?: UndiciT.Dispatcher | DispatcherOptions,
+): Promise<{
+  query?: Record<string, any> | undefined;
+  signal?: EventEmitter | AbortSignal | undefined;
+  dispatcher: UndiciT.Dispatcher;
+  headers: Record<string, string>;
+  throwOnError: true;
+}> {
+  const { Dispatcher } = await import("undici");
+  const dispatcher =
+    dispatcherOrDispatcherOptions instanceof Dispatcher
+      ? dispatcherOrDispatcherOptions
+      : await getDispatcher(requestUrl, dispatcherOrDispatcherOptions);
+
+  // We could use the global dispatcher if neither dispatcher nor dispatcherOptions were passed,
+  // but there's no way to configure it, so we don't do it.
+  // https://github.com/nodejs/undici/blob/961b76ad7cac17d23580d172702e11a080974f5d/lib/global.js#L9
+  return {
+    dispatcher,
+    headers: getHeaders(requestUrl, extraHeaders),
+    throwOnError: true,
+    ...(abortSignal !== undefined ? { signal: abortSignal } : {}),
+    ...(queryParams !== undefined ? { query: queryParams } : {}),
+  };
+}
+
+export function getHeaders(
+  requestUrl: string,
+  extraHeaders: Record<string, string> = {},
+): Record<string, string> {
+  const headers: Record<string, string> = {
+    ...extraHeaders,
+    "User-Agent": extraHeaders["User-Agent"] ?? DEFAULT_USER_AGENT,
+  };
+
+  const authHeader = getAuthHeader(requestUrl);
+  if (authHeader !== undefined) {
+    headers.Authorization = authHeader;
+  }
+
+  return headers;
+}
+
+export function getAuthHeader(requestUrl: string): string | undefined {
+  const parsedUrl = new URL(requestUrl);
+  if (parsedUrl.username === "") {
+    return undefined;
+  }
+
+  return `Basic ${Buffer.from(
+    `${parsedUrl.username}:${parsedUrl.password}`,
+  ).toString("base64")}`;
+}
+
+export async function getProxyDispatcher(
+  proxy: string,
+  options: Omit<UndiciT.ProxyAgent.Options, "uri">,
+): Promise<UndiciT.ProxyAgent> {
+  const { ProxyAgent } = await import("undici");
+
+  return new ProxyAgent({
+    uri: proxy,
+    ...options,
+  });
+}
+
+export async function getPoolDispatcher(
+  requestUrl: string,
+  options: UndiciT.Pool.Options,
+): Promise<UndiciT.Pool> {
+  const { Pool } = await import("undici");
+
+  const parsedUrl = new URL(requestUrl);
+  return new Pool(parsedUrl.origin, options);
+}
+
+export async function getBasicDispatcher(
+  options: UndiciT.Agent.Options,
+): Promise<UndiciT.Agent> {
+  const { Agent } = await import("undici");
+
+  return new Agent(options);
+}
+
+export function getBaseDispatcherOptions(
+  timeout: number = DEFAULT_TIMEOUT_IN_MILLISECONDS,
+  isTestDispatcher: boolean = false,
+): UndiciT.Client.Options {
+  // These have good defaults for production, but need to be tweaked to avoid hanging tests.
+  // https://github.com/nodejs/undici/blob/961b76ad7cac17d23580d172702e11a080974f5d/docs/docs/best-practices/writing-tests.md
+  const keepAliveTimeouts = isTestDispatcher
+    ? { keepAliveTimeout: 10, keepAliveMaxTimeout: 10 }
+    : {};
+
+  return {
+    headersTimeout: timeout,
+    bodyTimeout: timeout,
+    connectTimeout: timeout,
+    maxRedirections: DEFAULT_MAX_REDIRECTS,
+    ...keepAliveTimeouts,
+  };
+}
+
+export function sanitizeUrl(requestUrl: string): string {
+  const parsedUrl = new URL(requestUrl);
+  // Return only the origin to avoid leaking sensitive information
+  return parsedUrl.origin;
+}
+
+export function handleError(e: Error, requestUrl: string): void {
+  let causeCode: unknown;
+  if (isObject(e.cause)) {
+    causeCode = e.cause.code;
+  }
+  const errorCode = "code" in e ? e.code : causeCode;
+
+  if (errorCode === "ECONNREFUSED") {
+    throw new ConnectionRefusedError(requestUrl, e);
+  }
+
+  if (
+    errorCode === "UND_ERR_CONNECT_TIMEOUT" ||
+    errorCode === "UND_ERR_HEADERS_TIMEOUT" ||
+    errorCode === "UND_ERR_BODY_TIMEOUT"
+  ) {
+    throw new RequestTimeoutError(requestUrl, e);
+  }
+
+  if (errorCode === "UND_ERR_RESPONSE_STATUS_CODE") {
+    throw new ResponseStatusCodeError(requestUrl, e);
+  }
+}

package/src/lang.ts

@@ -0,0 +1,48 @@
+import { getDeepCloneFunction } from "./internal/lang.js";
+
+/**
+ * Creates a deep clone of the provided value.
+ *
+ * @param value The value to clone.
+ * @returns The deep clone of the provided value.
+ */
+export async function deepClone<T>(value: T): Promise<T> {
+  const _deepClone = await getDeepCloneFunction();
+
+  return _deepClone<T>(value);
+}
+
+/**
+ * Checks if two values are deeply equal.
+ *
+ * @param x The first value to compare.
+ * @param y The second value to compare.
+ * @returns True if the values are deeply equal, false otherwise.
+ */
+export async function deepEqual<T>(x: T, y: T): Promise<boolean> {
+  const { deepEqual: _deepEqual } = await import("fast-equals");
+
+  return _deepEqual(x, y);
+}
+
+/**
+ * Checks if a value is an object. This function returns false for arrays.
+ *
+ * @param value The value to check.
+ * @returns True if the value is an object, false otherwise.
+ */
+export function isObject(
+  value: unknown,
+): value is Record<string | symbol, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Pauses the execution for the specified number of seconds.
+ *
+ * @param seconds The number of seconds to pause the execution.
+ * @returns A promise that resolves after the specified number of seconds.
+ */
+export async function sleep(seconds: number): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
+}

package/src/number.ts

@@ -0,0 +1,38 @@
+import {
+  bytesToHexString,
+  hexStringToBytes,
+  hexStringToBigInt,
+  numberToHexString,
+  hexStringToNumber,
+} from "./hex.js";
+
+/**
+ * Converts a Uint8Array to a bigint.
+ *
+ * @param bytes The Uint8Array to convert.
+ * @returns The converted bigint.
+ */
+export function bytesToBigInt(bytes: Uint8Array): bigint {
+  return hexStringToBigInt(bytesToHexString(bytes));
+}
+
+/**
+ * Converts a Uint8Array to a number.
+ *
+ * @param bytes The Uint8Array to convert.
+ * @returns The converted number.
+ */
+export function bytesToNumber(bytes: Uint8Array): number {
+  return hexStringToNumber(bytesToHexString(bytes));
+}
+
+/**
+ * Converts a non-negative safe integer or bigint to a Uint8Array.
+ *
+ * @param value The number or bigint to convert.
+ * @returns The converted Uint8Array.
+ * @throws InvalidParameterError If the input is not a safe integer or is negative.
+ */
+export function numberToBytes(value: number | bigint): Uint8Array {
+  return hexStringToBytes(numberToHexString(value));
+}

package/src/package.ts

@@ -0,0 +1,143 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+
+import { ensureError } from "./error.js";
+import {
+  PackageJsonNotFoundError,
+  PackageJsonReadError,
+} from "./errors/package.js";
+import { exists, findUp, getRealPath, readJsonFile } from "./fs.js";
+import { getFilePath } from "./internal/package.js";
+import { ensureTrailingSlash } from "./string.js";
+
+/**
+ * The structure of a `package.json` file. This is a subset of the actual
+ * `package.json` file, if you need to access other fields you add them here.
+ */
+export interface PackageJson {
+  name: string;
+  version: string;
+  description?: string;
+  type?: "commonjs" | "module";
+  engines?: {
+    node?: string;
+  };
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  optionalDependencies?: Record<string, string>;
+}
+
+/**
+ * Searches for the nearest `package.json` file, starting from the directory of
+ * the provided file path or url string and moving up the directory tree.
+ *
+ * @param pathOrUrl A path or url string from which to start the search. The url
+ * must be a file url. This is useful when you want to find the nearest
+ * `package.json` file relative to the current module, as you can use
+ * `import.meta.url`.
+ * @returns The absolute path to the nearest `package.json` file.
+ * @throws PackageJsonNotFoundError If no `package.json` file is found.
+ */
+export async function findClosestPackageJson(
+  pathOrUrl: string,
+): Promise<string> {
+  const filePath = getFilePath(pathOrUrl);
+
+  if (filePath === undefined) {
+    throw new PackageJsonNotFoundError(pathOrUrl);
+  }
+
+  const packageJsonPath = await findUp("package.json", filePath);
+
+  if (packageJsonPath === undefined) {
+    throw new PackageJsonNotFoundError(pathOrUrl);
+  }
+
+  return packageJsonPath;
+}
+
+/**
+ * Reads the nearest `package.json` file, starting from provided path or url
+ * string and moving up the directory tree.
+ *
+ * @param pathOrUrl A path or url string from which to start the search. The url
+ * must be a file url. This is useful when you want to find the nearest
+ * `package.json` file relative to the current module, as you can use
+ * `import.meta.url`.
+ * @returns The contents of the nearest `package.json` file, parsed as a
+ * {@link PackageJson} object.
+ * @throws PackageJsonNotFoundError If no `package.json` file is found.
+ * @throws PackageJsonReadError If the `package.json` file is found but cannot
+ * be read.
+ */
+export async function readClosestPackageJson(
+  pathOrUrl: string,
+): Promise<PackageJson> {
+  const packageJsonPath = await findClosestPackageJson(pathOrUrl);
+  try {
+    return await readJsonFile<PackageJson>(packageJsonPath);
+  } catch (e) {
+    ensureError(e);
+    throw new PackageJsonReadError(packageJsonPath, e);
+  }
+}
+
+/**
+ * Finds the root directory of the nearest package, starting from the provided
+ * path or url string and moving up the directory tree.
+ *
+ * This function uses `findClosestPackageJson` to find the nearest `package.json`
+ * file and then returns the directory that contains that file.
+ *
+ * @param pathOrUrl A path or url string from which to start the search. The url
+ * must be a file url. This is useful when you want to find the nearest
+ * `package.json` file relative to the current module, as you can use
+ * `import.meta.url`.
+ * @returns The absolute path of the root directory of the nearest package.
+ */
+export async function findClosestPackageRoot(
+  filePathOrUrl: string,
+): Promise<string> {
+  const packageJsonPath = await findClosestPackageJson(filePathOrUrl);
+
+  return path.dirname(packageJsonPath);
+}
+
+/**
+ * Resolve a dependency starting by following the Node.js resolution algorithm
+ * starting from `from`, and returns the dependency's package.json file, or
+ * `undefined` if the dependency is not found.
+ *
+ * Note: This function uses Node.js's CommonJS resolution algorithm to find the
+ * package.json file, and works with packages using package#exports, even if
+ * they don't export the package.json file.
+ *
+ * @param from The absolute path from where to start the search (i.e. the file
+ *  importing the dependency, or its package root).
+ * @param dependencyPackageName The name of the package to find.
+ * @returns The absolute real path (resolved symlinks) of the package.json.
+ */
+export async function findDependencyPackageJson(
+  from: string,
+  dependencyPackageName: string,
+): Promise<string | undefined> {
+  const require = createRequire(ensureTrailingSlash(from));
+
+  const lookupPaths = require.resolve.paths(dependencyPackageName) ?? [];
+
+  const pathToTest = [...dependencyPackageName.split("/"), "package.json"];
+
+  for (const lookupPath of lookupPaths) {
+    const packageJsonPath = path.join(lookupPath, ...pathToTest);
+
+    if (await exists(packageJsonPath)) {
+      return getRealPath(packageJsonPath);
+    }
+  }
+}
+
+export {
+  PackageJsonNotFoundError,
+  PackageJsonReadError,
+} from "./errors/package.js";

package/src/path.ts

@@ -0,0 +1,45 @@
+import path from "node:path";
+
+/**
+ * Resolves a user-provided path into an absolute path.
+ *
+ * If the path is already absolute, it is returned as is, otherwise it is
+ * resolved relative to the root.
+ *
+ * @param root A root path to resolve relative paths against.
+ * @param target The target path to resolve.
+ * @returns An absolute path.
+ */
+export function resolveFromRoot(root: string, target: string): string {
+  if (path.isAbsolute(target)) {
+    return target;
+  }
+
+  return path.resolve(root, target);
+}
+
+/**
+ * Tries to return a shorter version of the path if its inside the given folder.
+ *
+ * This is useful for displaying paths in the terminal, as they can be shorter
+ * when they are insidde the current working directory. For example, if the
+ * current working directory is `/home/user/project`, and the path is
+ * `/home/user/project/contracts/File.sol`, the shorter path is
+ * `contracts/File.sol`.
+ *
+ * @param absolutePath The path to shorten.
+ * @param folder The absolute path to the folder.
+ * @returns The shorter path, if possible, or the original path.
+ */
+export function shortenPath(
+  absolutePath: string,
+  folder: string = process.cwd(),
+): string {
+  const relativePath = path.relative(folder, absolutePath);
+
+  if (relativePath.length < absolutePath.length) {
+    return relativePath;
+  }
+
+  return absolutePath;
+}