@nomicfoundation/hardhat-utils 4.0.5 → 4.1.1

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/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/subprocess.ts

@@ -6,6 +6,8 @@ import {
 } from "./errors/subprocess.js";
 import { exists, isDirectory } from "./fs.js";
 
+export { SubprocessFileNotFoundError, SubprocessPathIsDirectoryError };
+
 /**
  * Spawns a detached subprocess to execute a given file with optional arguments.
  *

package/src/synchronization.ts

@@ -1,10 +1,9 @@
 import { randomUUID } from "node:crypto";
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-
-import debug from "debug";
+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";
 import {
   BaseMultiProcessMutexError,
@@ -30,7 +29,7 @@ export {
   StaleMultiProcessMutexError,
 } from "./errors/synchronization.js";
 
-const log = debug("hardhat:util:multi-process-mutex");
+const log = createDebug("hardhat:utils:synchronization");
 
 const PROCESS_SESSION_ID = randomUUID();
 const DEFAULT_TIMEOUT_MS = 60_000;
@@ -383,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(),
       );
     }
 
@@ -476,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,
@@ -622,3 +621,212 @@ export class AsyncMutex {
     });
   }
 }
+
+interface SharedPromiseSuccessfulExecutionResult<ValueT> {
+  success: true;
+  value: ValueT;
+}
+
+type SharedPromiseExecutionResult<ValueT> =
+  | SharedPromiseSuccessfulExecutionResult<ValueT>
+  | { success: false; error: unknown };
+
+type SharedPromiseCachedResult<ValueT> =
+  // We wrapped the resolved value so that we can distinguish not-cached from
+  // `undefined` cached values, and between Promise and value.
+  | SharedPromiseSuccessfulExecutionResult<ValueT>
+  | Promise<SharedPromiseExecutionResult<ValueT>>;
+
+/**
+ * A class that deduplicates the concurrent computations of an asynchronous
+ * operation based on a string key, by sharing the same Promise for all
+ * concurrent calls.
+ *
+ * This class is useful when the operation is expensive, or you need to
+ * guarantee that it's only executed once per key.
+ *
+ * For this cache to work correctly, the operation has to be either idempotent,
+ * or virtually idempotent (e.g. reading the same file multiple times in a very
+ * short time, in a context where it shouldn't be changed).
+ *
+ * The results of the first operation run per key are cached during the lifetime
+ * of the class, or until the `delete` or `clear` methods are called.
+ *
+ * Note that you should always use the same function/operation per cache key. If
+ * you call `getOrCompute` with the same key but different functions, the
+ * first function will be used for all the calls.
+ *
+ * Notes on async stack traces: This class is designed to preserve as much as
+ * possible of the producer async stack trace, including the place where the
+ * first `getOrCompute` computation is started and where the producer throws. To
+ * achieve this, you should provide an async lambda of the shape
+ * `async () => await myFunction()`, instead of directly passing `myFunction`.
+ * You should also try to immediately await the calls to `getOrCompute`.
+ *
+ * Concurrent callers for the same in-flight computation receive the same
+ * original thrown value, so their own `getOrCompute` call site won't
+ * necessarily be present in the error stack.
+ *
+ * Notes on concurrency: `getOrCompute` stores the in-flight promise in the
+ * cache before invoking the producer function. Subsequent calls with the same
+ * key, including synchronous same-key reentrant calls from the producer,
+ * observe that promise and await the same computation instead of invoking their
+ * own function. A producer must still not await a same-key reentrant call
+ * before completing, because it would wait on its own in-flight result.
+ *
+ * This guarantee only applies while the cache entry remains installed. Calling
+ * `delete` or `clear` during an in-flight computation lets later callers start
+ * a new computation, and the older in-flight result won't repopulate the cache.
+ */
+export class SharedPromiseCache<ValueT> {
+  readonly #cache = new Map<string, SharedPromiseCachedResult<ValueT>>();
+
+  /**
+   * Returns the cached value associated to the key, or computes it if needed,
+   * guaranteeing that it's only computed once per key.
+   *
+   * @param key The cache key associated to the value.
+   * @param fn The function that computes the value when it's not cached. Please
+   * read the class docs to understand the requirements it should meet.
+   * @returns The value.
+   * @throws The original value thrown or rejected by the function. Concurrent
+   * callers for the same in-flight computation observe the same thrown value, so
+   * their stack reflects the original computation, not necessarily each
+   * awaiting call site.
+   */
+  public async getOrCompute(
+    key: string,
+    fn: () => Promise<ValueT>,
+  ): Promise<ValueT> {
+    const cached = this.#cache.get(key);
+    if (cached !== undefined) {
+      if (!(cached instanceof Promise)) {
+        return cached.value;
+      }
+
+      const cachedResult = await cached;
+
+      this.#updateResolvedPromiseCache(key, cached, cachedResult);
+
+      if (cachedResult.success) {
+        return cachedResult.value;
+      }
+
+      throw cachedResult.error;
+    }
+
+    // Create and cache the in-flight promise before invoking `fn`, because
+    // `fn` can synchronously re-enter `getOrCompute` with the same key. The
+    // reentrant call must observe this promise instead of a cache miss, or it
+    // could start a second computation for the same key.
+    //
+    // `Promise.withResolvers` lets the first caller still await `fn` directly,
+    // preserving the producer async stack.
+    const { promise, resolve } =
+      Promise.withResolvers<SharedPromiseExecutionResult<ValueT>>();
+
+    this.#cache.set(key, promise);
+
+    let result: SharedPromiseExecutionResult<ValueT>;
+
+    try {
+      const value = await fn();
+      result = { success: true, value };
+    } catch (error) {
+      result = { success: false, error };
+    }
+
+    resolve(result);
+
+    this.#updateResolvedPromiseCache(key, promise, result);
+
+    if (result.success) {
+      return result.value;
+    }
+
+    throw result.error;
+  }
+
+  /**
+   * Returns the cached value associated to the key without invoking any
+   * producer. If the entry is in-flight, the value is not yet available and
+   * this method returns `undefined` exactly as it would for a missing key.
+   *
+   * Use this for synchronous fast-path lookups; if the result is `undefined`
+   * and you still want to compute the value, fall through to `getOrCompute`.
+   *
+   * Note that if `ValueT` includes `undefined` as a valid value, you won't be
+   * able to distinguish between a cached `undefined` and a missing/in-flight
+   * entry, but that's an intentional tradeoff to keep this method simple.
+   *
+   * @param key The cache key.
+   * @returns The cached value, or `undefined` if the key is missing or
+   * in-flight.
+   */
+  public peek(key: string): ValueT | undefined {
+    const cached = this.#cache.get(key);
+    if (cached === undefined || cached instanceof Promise) {
+      return undefined;
+    }
+    return cached.value;
+  }
+
+  /**
+   * Iterates over the entries that are successfully resolved, yielding
+   * `[key, value]` pairs. In-flight entries are skipped because their value
+   * is not yet known, and failed ones are removed from the cache.
+   *
+   * Producers are never invoked.
+   */
+  public *resolvedEntries(): IterableIterator<[string, ValueT]> {
+    for (const [key, cached] of this.#cache) {
+      if (!(cached instanceof Promise)) {
+        yield [key, cached.value];
+      }
+    }
+  }
+
+  /**
+   * Deletes the cached value associated to the key, if any. Note that this does
+   * not cancel any ongoing operation. Callers that already observed the
+   * in-flight promise will still wait for the original operation to complete,
+   * but callers that start after the deletion may start a new computation.
+   *
+   * @param key The cache key to delete.
+   */
+  public delete(key: string): void {
+    this.#cache.delete(key);
+  }
+
+  /**
+   * Clears the cache, removing all the stored values, but without cancelling
+   * any ongoing operation.
+   */
+  public clear(): void {
+    this.#cache.clear();
+  }
+
+  /**
+   * Updates the cache if needed once a promise got resolved.
+   *
+   * @param key The cache key.
+   * @param promise The promise that got resolved.
+   * @param result The result of the resolved promise.
+   */
+  #updateResolvedPromiseCache(
+    key: string,
+    promise: Promise<SharedPromiseExecutionResult<ValueT>>,
+    result: SharedPromiseExecutionResult<ValueT>,
+  ): void {
+    // We only update the cache if the cached promise is still the one that got
+    // resolved, which may not always be the case. The reason is that the
+    // resolved promise may have been deleted and/or replaced in the cache.
+    if (this.#cache.get(key) === promise) {
+      if (result.success) {
+        this.#cache.set(key, { success: true, value: result.value });
+      } else {
+        this.#cache.delete(key);
+      }
+    }
+  }
+}