@nomicfoundation/hardhat-utils 4.1.0 → 4.1.2

package/src/fs.ts

@@ -1,4 +1,5 @@
-import type { JsonTypes, ParsedElementInfo } from "@streamparser/json-node";
+import type * as StreamParserJson from "@streamparser/json-node";
+import type * as JsonStreamStringify from "json-stream-stringify";
 import type { FileHandle } from "node:fs/promises";
 
 import fsPromises from "node:fs/promises";
@@ -6,9 +7,6 @@ import { tmpdir } from "node:os";
 import path from "node:path";
 import { pipeline } from "node:stream/promises";
 
-import { JSONParser } from "@streamparser/json-node";
-import { JsonStreamStringify } from "json-stream-stringify";
-
 import { ensureError, ensureNodeErrnoExceptionError } from "./error.js";
 import {
   FileNotFoundError,
@@ -21,10 +19,18 @@ import {
   DirectoryNotEmptyError,
 } from "./errors/fs.js";
 import {
-  isDirectoryDirentAware,
-  readdirWithFileTypesOrEmpty,
+  collectAllDirectoriesMatching,
+  collectAllFilesMatching,
 } from "./internal/fs.js";
 
+// We don't load @streamparser/json-node on startup because it's only
+// used by readJsonFileAsStream for very large JSON files.
+let streamParserJson: typeof StreamParserJson | undefined;
+
+// We don't load json-stream-stringify on startup because it's only
+// used by writeJsonFileAsStream for very large JSON objects.
+let jsonStreamStringify: typeof JsonStreamStringify | undefined;
+
 const AMBIGUOUS_CASING_DIR_ENTRY = Symbol("ambiguous");
 
 type CaseFoldedEntry = string | typeof AMBIGUOUS_CASING_DIR_ENTRY;
@@ -310,33 +316,10 @@ export async function getAllFilesMatching(
   matches?: (absolutePathToFile: string) => Promise<boolean> | boolean,
   directoryFilter?: (absolutePathToDir: string) => Promise<boolean> | boolean,
 ): Promise<string[]> {
-  const dirContent = await readdirWithFileTypesOrEmpty(dirFrom);
-
-  const results = await Promise.all(
-    dirContent.map(async (dirent) => {
-      const absolutePathToFile = path.join(dirFrom, dirent.name);
-      if (await isDirectoryDirentAware(absolutePathToFile, dirent)) {
-        if (
-          directoryFilter === undefined ||
-          (await directoryFilter(absolutePathToFile))
-        ) {
-          return await getAllFilesMatching(
-            absolutePathToFile,
-            matches,
-            directoryFilter,
-          );
-        }
+  const results: string[] = [];
+  await collectAllFilesMatching(dirFrom, results, matches, directoryFilter);
 
-        return [];
-      } else if (matches === undefined || (await matches(absolutePathToFile))) {
-        return absolutePathToFile;
-      } else {
-        return [];
-      }
-    }),
-  );
-
-  return results.flat();
+  return results;
 }
 
 /**
@@ -358,24 +341,10 @@ export async function getAllDirectoriesMatching(
   dirFrom: string,
   matches?: (absolutePathToDir: string) => Promise<boolean> | boolean,
 ): Promise<string[]> {
-  const dirContent = await readdirWithFileTypesOrEmpty(dirFrom);
-
-  const results = await Promise.all(
-    dirContent.map(async (dirent) => {
-      const absolutePathToFile = path.join(dirFrom, dirent.name);
-      if (!(await isDirectoryDirentAware(absolutePathToFile, dirent))) {
-        return [];
-      }
+  const results: string[] = [];
+  await collectAllDirectoriesMatching(dirFrom, results, matches);
 
-      if (matches === undefined || (await matches(absolutePathToFile))) {
-        return absolutePathToFile;
-      }
-
-      return await getAllDirectoriesMatching(absolutePathToFile, matches);
-    }),
-  );
-
-  return results.flat();
+  return results;
 }
 
 /**
@@ -459,9 +428,13 @@ export async function readJsonFileAsStream<T>(
 
     const fileReadStream = fileHandle.createReadStream();
 
+    if (streamParserJson === undefined) {
+      streamParserJson = await import("@streamparser/json-node");
+    }
+
     // NOTE: We set a separator to disable self-closing to be able to use the parser
     // in the stream.pipeline context; see https://github.com/juanjoDiaz/streamparser-json/issues/47
-    const jsonParser = new JSONParser({
+    const jsonParser = new streamParserJson.JSONParser({
       separator: "",
     });
 
@@ -469,9 +442,12 @@ export async function readJsonFileAsStream<T>(
       fileReadStream,
       jsonParser,
       async (
-        elements: AsyncIterable<ParsedElementInfo.ParsedElementInfo>,
+        elements: AsyncIterable<StreamParserJson.ParsedElementInfo.ParsedElementInfo>,
       ): Promise<any | undefined> => {
-        let value: JsonTypes.JsonPrimitive | JsonTypes.JsonStruct | undefined;
+        let value:
+          | StreamParserJson.JsonTypes.JsonPrimitive
+          | StreamParserJson.JsonTypes.JsonStruct
+          | undefined;
         for await (const element of elements) {
           value = element.value;
         }
@@ -560,7 +536,11 @@ export async function writeJsonFileAsStream<T>(
   try {
     fileHandle = await fsPromises.open(absolutePathToFile, "w");
 
-    const jsonStream = new JsonStreamStringify(object);
+    if (jsonStreamStringify === undefined) {
+      jsonStreamStringify = await import("json-stream-stringify");
+    }
+
+    const jsonStream = new jsonStreamStringify.JsonStreamStringify(object);
     const fileWriteStream = fileHandle.createWriteStream();
 
     await pipeline(jsonStream, fileWriteStream);

package/src/internal/bytecode.ts

@@ -29,6 +29,17 @@ export interface LibraryAddresses {
   [contractName: string]: PrefixedHexString;
 }
 
+export interface BytecodeReplacement {
+  start: number;
+  length: number;
+  value: string;
+}
+
+interface LibraryLinksIndex {
+  byName: Map<string, LibraryLink[]>;
+  byFqn: Map<string, LibraryLink>;
+}
+
 /**
  * Check that the provided library addresses are valid Ethereum addresses.
  * If any of them are not, an InvalidLibraryAddressError is thrown.
@@ -61,13 +72,15 @@ export function checkAmbiguousOrUnnecessaryLinks(
 ): void {
   const ambiguousLibraries: Record<string, LibraryLink[]> = {};
   const unnecessaryLibraries: string[] = [];
+  const neededLibrariesIndex = indexLibraryLinks(neededLibraries);
 
   for (const providedLibraryName of Object.keys(providedLibraries)) {
-    const matchingLibraries = neededLibraries.filter(
-      ({ libraryName, libraryFqn }) =>
-        libraryName === providedLibraryName ||
-        libraryFqn === providedLibraryName,
-    );
+    const matchingLibraryByFqn =
+      neededLibrariesIndex.byFqn.get(providedLibraryName);
+    const matchingLibraries =
+      matchingLibraryByFqn !== undefined
+        ? [matchingLibraryByFqn]
+        : neededLibrariesIndex.byName.get(providedLibraryName) ?? [];
 
     if (matchingLibraries.length > 1) {
       ambiguousLibraries[providedLibraryName] = matchingLibraries;
@@ -85,6 +98,24 @@ export function checkAmbiguousOrUnnecessaryLinks(
   }
 }
 
+function indexLibraryLinks(neededLibraries: LibraryLink[]): LibraryLinksIndex {
+  const byName = new Map<string, LibraryLink[]>();
+  const byFqn = new Map<string, LibraryLink>();
+
+  for (const neededLibrary of neededLibraries) {
+    byFqn.set(neededLibrary.libraryFqn, neededLibrary);
+
+    const sameNameLibraries = byName.get(neededLibrary.libraryName);
+    if (sameNameLibraries === undefined) {
+      byName.set(neededLibrary.libraryName, [neededLibrary]);
+    } else {
+      sameNameLibraries.push(neededLibrary);
+    }
+  }
+
+  return { byName, byFqn };
+}
+
 /**
  * Check that each library is only provided once, either by its name or its
  * fully qualified name. If a library is provided more than once, an
@@ -127,3 +158,31 @@ export function checkMissingLibraryAddresses(
 
   throw new MissingLibrariesError(missingLibraries);
 }
+
+/**
+ * Apply a set of replacements to a bytecode string, returning the resulting
+ * bytecode. Each replacement overwrites `length` characters starting at
+ * `start` with `value`. Replacements must not overlap.
+ */
+export function applyBytecodeReplacements(
+  bytecode: string,
+  replacements: BytecodeReplacement[],
+): string {
+  if (replacements.length === 0) {
+    return bytecode;
+  }
+
+  replacements.sort((a, b) => a.start - b.start);
+
+  const parts: string[] = [];
+  let position = 0;
+
+  for (const { start, length, value } of replacements) {
+    parts.push(bytecode.slice(position, start), value);
+    position = start + length;
+  }
+
+  parts.push(bytecode.slice(position));
+
+  return parts.join("");
+}

package/src/internal/fs.ts

@@ -1,6 +1,7 @@
 import type { Dirent } from "node:fs";
 
 import fsPromises from "node:fs/promises";
+import path from "node:path";
 
 import { ensureNodeErrnoExceptionError } from "../error.js";
 import { FileSystemAccessError, NotADirectoryError } from "../errors/fs.js";
@@ -55,3 +56,72 @@ export async function isDirectoryDirentAware(
 
   return await isDirectory(absolutePath);
 }
+
+/**
+ * Recursively walk the directory tree rooted at `dirFrom`, appending the
+ * absolute paths of every file accepted by `matches` to `results`. Descent
+ * into a subdirectory is gated by `directoryFilter`. When either callback is
+ * omitted, every file or directory is accepted.
+ */
+export async function collectAllFilesMatching(
+  dirFrom: string,
+  results: string[],
+  matches?: (absolutePathToFile: string) => Promise<boolean> | boolean,
+  directoryFilter?: (absolutePathToDir: string) => Promise<boolean> | boolean,
+): Promise<void> {
+  const dirContent = await readdirWithFileTypesOrEmpty(dirFrom);
+
+  await Promise.all(
+    dirContent.map(async (dirent) => {
+      const absolutePathToFile = path.join(dirFrom, dirent.name);
+      if (await isDirectoryDirentAware(absolutePathToFile, dirent)) {
+        if (
+          directoryFilter === undefined ||
+          (await directoryFilter(absolutePathToFile))
+        ) {
+          await collectAllFilesMatching(
+            absolutePathToFile,
+            results,
+            matches,
+            directoryFilter,
+          );
+        }
+
+        return;
+      } else if (matches === undefined || (await matches(absolutePathToFile))) {
+        results.push(absolutePathToFile);
+      }
+    }),
+  );
+}
+
+/**
+ * Recursively walk the directory tree rooted at `dirFrom`, appending the
+ * absolute paths of every directory accepted by `matches` to `results`. When
+ * a directory matches, its descendants are not explored; when it does not,
+ * the walk continues into its subdirectories. When `matches` is omitted,
+ * every directory is accepted and recursion stops at the top level.
+ */
+export async function collectAllDirectoriesMatching(
+  dirFrom: string,
+  results: string[],
+  matches?: (absolutePathToDir: string) => Promise<boolean> | boolean,
+): Promise<void> {
+  const dirContent = await readdirWithFileTypesOrEmpty(dirFrom);
+
+  await Promise.all(
+    dirContent.map(async (dirent) => {
+      const absolutePathToFile = path.join(dirFrom, dirent.name);
+      if (!(await isDirectoryDirentAware(absolutePathToFile, dirent))) {
+        return;
+      }
+
+      if (matches === undefined || (await matches(absolutePathToFile))) {
+        results.push(absolutePathToFile);
+        return;
+      }
+
+      await collectAllDirectoriesMatching(absolutePathToFile, results, matches);
+    }),
+  );
+}

package/src/internal/global-dir.ts

@@ -1,9 +1,15 @@
-import envPaths from "env-paths";
+import type { Paths } from "env-paths";
 
 export const HARDHAT_PACKAGE_NAME = "hardhat";
 
-export async function generatePaths(
-  packageName: string,
-): Promise<envPaths.Paths> {
+// We don't load env-paths on startup because this module is transitively
+// imported from many places but generatePaths is rarely called during
+// bootstrap.
+let envPaths: ((name: string) => Paths) | undefined;
+
+export async function generatePaths(packageName: string): Promise<Paths> {
+  if (envPaths === undefined) {
+    ({ default: envPaths } = await import("env-paths"));
+  }
   return envPaths(packageName);
 }

package/src/internal/lang.ts

@@ -1,11 +1,15 @@
-import { createCustomEqual } from "fast-equals";
-import rfdc from "rfdc";
+import type Rfdc from "rfdc";
 
 import { isObject } from "../lang.js";
 
-let clone: ReturnType<typeof rfdc> | null = null;
-export function getDeepCloneFunction(): <T>(input: T) => T {
-  if (clone === null) {
+// We don't load rfdc on startup because it adds unnecessary
+// overhead when this module is transitively imported but deep clone
+// is not used.
+let clone: ReturnType<typeof Rfdc> | undefined;
+
+export async function getDeepCloneFunction(): Promise<ReturnType<typeof Rfdc>> {
+  if (clone === undefined) {
+    const { default: rfdc } = await import("rfdc");
     clone = rfdc();
   }
 
@@ -53,6 +57,9 @@ export function deepMergeImpl<T extends object, S extends object>(
   return result;
 }
 
+// We don't load fast-equals on startup because it adds unnecessary
+// overhead when this module is transitively imported but deep equal
+// is not used.
 let cachedCustomEqual: ((a: unknown, b: unknown) => boolean) | undefined;
 
 /**
@@ -62,11 +69,13 @@ let cachedCustomEqual: ((a: unknown, b: unknown) => boolean) | undefined;
  * @param y The second value to compare.
  * @returns True if the values are deeply equal, false otherwise.
  */
-export function customFastEqual<T>(x: T, y: T): boolean {
+export async function customFastEqual<T>(x: T, y: T): Promise<boolean> {
   if (cachedCustomEqual !== undefined) {
     return cachedCustomEqual(x, y);
   }
 
+  const { createCustomEqual } = await import("fast-equals");
+
   cachedCustomEqual = createCustomEqual({
     createCustomConfig: (defaultConfig) => ({
       areTypedArraysEqual: (a, b, state) => {

package/src/lang.ts

@@ -11,7 +11,7 @@ import {
  * @returns The deep clone of the provided value.
  */
 export async function deepClone<T>(value: T): Promise<T> {
-  const _deepClone = getDeepCloneFunction();
+  const _deepClone = await getDeepCloneFunction();
 
   return _deepClone<T>(value);
 }
@@ -24,7 +24,7 @@ export async function deepClone<T>(value: T): Promise<T> {
  * @returns True if the values are deeply equal, false otherwise.
  */
 export async function deepEqual<T>(x: T, y: T): Promise<boolean> {
-  return customFastEqual(x, y);
+  return await customFastEqual(x, y);
 }
 
 /**

package/src/path.ts

@@ -53,3 +53,26 @@ export function shortenPath(absolutePath: string): string {
 
   return absolutePath;
 }
+
+/**
+ * Returns a version of {@link name} that is safe to use as a single filename
+ * component on POSIX, macOS, and Windows.
+ *
+ * Strips characters that are reserved on at least one of those platforms
+ * (`<>:"/\|?*` and ASCII control chars), trims trailing dots and whitespace
+ * (Windows silently strips them on write), and falls back to `_` if the
+ * result is empty or one of the path-traversal literals `.` / `..`.
+ *
+ * @param name The string to sanitize.
+ * @returns A non-empty filename-safe string.
+ */
+export function sanitizeFilename(name: string): string {
+  let result = name.replace(/[<>:"/\\|?*\x00-\x1F\x7F]/g, "");
+  result = result.replace(/[\s.]+$/, "");
+
+  if (result === "" || result === "." || result === "..") {
+    result = "_";
+  }
+
+  return result;
+}

package/src/request.ts

@@ -1,11 +1,11 @@
 import type EventEmitter from "node:events";
 import type { FileHandle } from "node:fs/promises";
 import type { ParsedUrlQueryInput } from "node:querystring";
-import type * as UndiciT from "undici";
+import type * as Undici from "undici";
 
 import { open } from "node:fs/promises";
 import querystring from "node:querystring";
-import stream from "node:stream/promises";
+import { pipeline } from "node:stream/promises";
 
 import { ensureError } from "./error.js";
 import {
@@ -24,18 +24,18 @@ import {
   handleError,
 } from "./internal/request.js";
 
-export const DEFAULT_TIMEOUT_IN_MILLISECONDS = 300_000; // Aligned with unidici
+export const DEFAULT_TIMEOUT_IN_MILLISECONDS = 300_000; // Aligned with undici
 export const DEFAULT_MAX_REDIRECTS = 10;
 export const DEFAULT_POOL_MAX_CONNECTIONS = 128;
 export const DEFAULT_USER_AGENT = "Hardhat";
 
-export type Dispatcher = UndiciT.Dispatcher;
-export type TestDispatcher = UndiciT.MockAgent;
-export type Interceptable = UndiciT.Interceptable;
+export type Dispatcher = Undici.Dispatcher;
+export type TestDispatcher = Undici.MockAgent;
+export type Interceptable = Undici.Interceptable;
 
 // We don't load undici on startup because this package is transitively imported
 // from too many places and it's too complex to optimize case by case.
-let undici: typeof UndiciT | undefined;
+let undici: typeof Undici | undefined;
 
 /**
  * Options to configure the dispatcher.
@@ -90,7 +90,7 @@ export interface HttpResponse {
 export async function getRequest(
   url: string,
   requestOptions: RequestOptions = {},
-  dispatcherOrDispatcherOptions?: UndiciT.Dispatcher | DispatcherOptions,
+  dispatcherOrDispatcherOptions?: Undici.Dispatcher | DispatcherOptions,
 ): Promise<HttpResponse> {
   if (undici === undefined) {
     undici = await import("undici");
@@ -132,7 +132,7 @@ export async function postJsonRequest(
   url: string,
   body: unknown,
   requestOptions: RequestOptions = {},
-  dispatcherOrDispatcherOptions?: UndiciT.Dispatcher | DispatcherOptions,
+  dispatcherOrDispatcherOptions?: Undici.Dispatcher | DispatcherOptions,
 ): Promise<HttpResponse> {
   if (undici === undefined) {
     undici = await import("undici");
@@ -179,7 +179,7 @@ export async function postFormRequest(
   url: string,
   body: unknown,
   requestOptions: RequestOptions = {},
-  dispatcherOrDispatcherOptions?: UndiciT.Dispatcher | DispatcherOptions,
+  dispatcherOrDispatcherOptions?: Undici.Dispatcher | DispatcherOptions,
 ): Promise<HttpResponse> {
   if (undici === undefined) {
     undici = await import("undici");
@@ -225,7 +225,7 @@ export async function download(
   url: string,
   destination: string,
   requestOptions: RequestOptions = {},
-  dispatcherOrDispatcherOptions?: UndiciT.Dispatcher | DispatcherOptions,
+  dispatcherOrDispatcherOptions?: Undici.Dispatcher | DispatcherOptions,
 ): Promise<void> {
   let statusCode: number | undefined;
   let tempFilePath: string | undefined;
@@ -240,7 +240,7 @@ export async function download(
       url,
       requestOptions,
       dispatcherOrDispatcherOptions,
-    )) as UndiciT.Dispatcher.ResponseData;
+    )) as Undici.Dispatcher.ResponseData;
     const { body } = response;
     statusCode = response.statusCode;
 
@@ -257,7 +257,7 @@ export async function download(
 
       const fileStream = fileHandle.createWriteStream();
 
-      await stream.pipeline(body, fileStream);
+      await pipeline(body, fileStream);
     } finally {
       // NOTE: Historically, not closing the file handle caused issues on Windows,
       // for example, when trying to move the file previously written to by this function
@@ -284,9 +284,9 @@ export async function download(
 
 /**
  * Creates a dispatcher based on the provided options.
- * If the `proxy` option is set, it creates a {@link UndiciT.ProxyAgent} dispatcher.
- * If the `pool` option is set to `true`, it creates a {@link UndiciT.Pool} dispatcher.
- * Otherwise, it creates a basic {@link UndiciT.Agent} dispatcher.
+ * If the `proxy` option is set, it creates a {@link Undici.ProxyAgent} dispatcher.
+ * If the `pool` option is set to `true`, it creates a {@link Undici.Pool} dispatcher.
+ * Otherwise, it creates a basic {@link Undici.Agent} dispatcher.
  *
  * @param url The url to make requests to.
  * @param options The options to configure the dispatcher. See {@link DispatcherOptions}.

package/src/synchronization.ts

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
+import fs from "node:fs";
+import { hostname } from "node:os";
+import path from "node:path";
 
 import { createDebug } from "./debug.js";
 import { ensureError, ensureNodeErrnoExceptionError } from "./error.js";
@@ -382,11 +382,11 @@ export class MultiProcessMutex {
     }
 
     // Different hostname — can't verify PID remotely
-    if (metadata.hostname !== os.hostname()) {
+    if (metadata.hostname !== hostname()) {
       throw new IncompatibleHostnameMultiProcessMutexError(
         lockPath,
         metadata.hostname,
-        os.hostname(),
+        hostname(),
       );
     }
 
@@ -475,7 +475,7 @@ export class MultiProcessMutex {
   #buildMetadata(): LockMetadata {
     return {
       pid: process.pid,
-      hostname: os.hostname(),
+      hostname: hostname(),
       createdAt: Date.now(),
       ...(process.getuid !== undefined ? { uid: process.getuid() } : {}),
       platform: process.platform,