@nomicfoundation/hardhat-utils 4.0.5 → 4.1.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @nomicfoundation/hardhat-utils
 
+## 4.1.0
+
+### Minor Changes
+
+- [#8205](https://github.com/NomicFoundation/hardhat/pull/8205) [`99a4556`](https://github.com/NomicFoundation/hardhat/commit/99a4556698e1d0776951fb160641f5e2529b68ee) Thanks [@alcuadrado](https://github.com/alcuadrado)! - Introduce the SharedPromiseCache synchronization primitive
+
+### Patch Changes
+
+- [#8219](https://github.com/NomicFoundation/hardhat/pull/8219) [`2cad309`](https://github.com/NomicFoundation/hardhat/commit/2cad309eb8d35fcc5d2aba5d75a5af4d63d50508) Thanks [@schaable](https://github.com/schaable)! - Improved performance by replacing the semver dependency with a lightweight in-tree implementation.
+
+- [#8196](https://github.com/NomicFoundation/hardhat/pull/8196) [`73436aa`](https://github.com/NomicFoundation/hardhat/commit/73436aaa1ddac805f8d855627b5b40ad69cf7d2e) Thanks [@alcuadrado](https://github.com/alcuadrado)! - Export missing error types
+
+- [#8207](https://github.com/NomicFoundation/hardhat/pull/8207) [`d594209`](https://github.com/NomicFoundation/hardhat/commit/d59420968bffca83e1ad2712c6881d19cc7e1a99) Thanks [@alcuadrado](https://github.com/alcuadrado)! - Improved performance by replacing the debug logging library with a lightweight in-tree implementation.
+
+- [#8189](https://github.com/NomicFoundation/hardhat/pull/8189) [`b5ca1ae`](https://github.com/NomicFoundation/hardhat/commit/b5ca1aee1eb2571ec23f54ac8a9b2c39a90361c6) Thanks [@alcuadrado](https://github.com/alcuadrado)! - Introduce a TrueCasePathResolver class to optimize repeated filesystem casing resolution
+
 ## 4.0.5
 
 ### Patch Changes

package/dist/src/debug.d.ts

@@ -1,16 +1,48 @@
 /**
- * A simple decorator that adds debug logging for when a method is entered and exited.
+ * A logger function returned by {@link createDebug}.
+ * The `enabled` property is `true` when the logger will produce output.
+ */
+export interface DebugLogger {
+    (format: unknown, ...args: unknown[]): void;
+    readonly enabled: boolean;
+}
+/**
+ * Creates a namespaced logger controlled by the `DEBUG` env var.
  *
- * This decorator is meant to be used for debugging purposes only. It should not be committed in runtime code.
+ * If `namespace` matches `DEBUG`, the logger writes to `process.stderr`;
+ * otherwise, it is a no-op. Additionally, `logger.enabled` is `true` when
+ * the namespace matches `DEBUG`, allowing you to conditionally run expensive
+ * diagnostics.
  *
- * Example usage:
+ * `DEBUG` should be a comma- or whitespace-separated list of patterns.
+ * `*` is a wildcard and a leading `-` negates a pattern (e.g.
+ * `hardhat:*,-hardhat:noisy`).
  *
- * ```
- * class MyClass {
- *   @withDebugLogs("MyClass:exampleClassMethod")
- *   public function exampleClassMethod(...)
+ * Messages are formatted using `node:util.format`, allowing you to use format
+ * specifiers like `%O`, `%o`, `%s`, `%d`, `%j`. Extra arguments without a
+ * matching specifier are inspected automatically.
+ *
+ * Output is colorized per namespace when `stderr` is a TTY. Set
+ * `DEBUG_COLORS=no` or `false` to disable colors.
+ *
+ * @example
+ * ```ts
+ * const log = createDebug("hardhat:utils:foo");
+ * log("Starting up");
+ * log("Received %O", payload);
+ * log("Saved data", id, filePath);
+ *
+ * if (log.enabled) {
+ *   // expensive diagnostics that should only run while debugging
  * }
  * ```
+ *
+ * ```sh
+ * DEBUG="hardhat:*,-hardhat:noisy" DEBUG_COLORS=no pnpm hardhat run script.js
+ * ```
+ *
+ * @param namespace Namespace used for filtering and as the log prefix.
+ * @returns Logger function, or a shared no-op if disabled.
  */
-export declare function withDebugLogs<This, Args extends any[], Return>(tag?: string): (originalMethod: (this: This, ...args: Args) => Return, _context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>) => (this: This, ...args: Args) => Return;
+export declare function createDebug(namespace: string): DebugLogger;
 //# sourceMappingURL=debug.d.ts.map

package/dist/src/debug.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../src/debug.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,SAAS,GAAG,EAAE,EAAE,MAAM,EAC5D,GAAG,GAAE,MAAW,IAGd,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,MAAM,EACrD,UAAU,2BAA2B,CACnC,IAAI,EACJ,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,MAAM,CACtC,KACA,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,MAAM,CAYzC"}
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../src/debug.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,CA+B1D"}

package/dist/src/debug.js

@@ -1,28 +1,64 @@
-import debugLib from "debug";
+import { formatWithOptions } from "node:util";
+import { NOOP, isEnabled, selectColor, useColors } from "./internal/debug.js";
 /**
- * A simple decorator that adds debug logging for when a method is entered and exited.
+ * Creates a namespaced logger controlled by the `DEBUG` env var.
  *
- * This decorator is meant to be used for debugging purposes only. It should not be committed in runtime code.
+ * If `namespace` matches `DEBUG`, the logger writes to `process.stderr`;
+ * otherwise, it is a no-op. Additionally, `logger.enabled` is `true` when
+ * the namespace matches `DEBUG`, allowing you to conditionally run expensive
+ * diagnostics.
  *
- * Example usage:
+ * `DEBUG` should be a comma- or whitespace-separated list of patterns.
+ * `*` is a wildcard and a leading `-` negates a pattern (e.g.
+ * `hardhat:*,-hardhat:noisy`).
  *
- * ```
- * class MyClass {
- *   @withDebugLogs("MyClass:exampleClassMethod")
- *   public function exampleClassMethod(...)
+ * Messages are formatted using `node:util.format`, allowing you to use format
+ * specifiers like `%O`, `%o`, `%s`, `%d`, `%j`. Extra arguments without a
+ * matching specifier are inspected automatically.
+ *
+ * Output is colorized per namespace when `stderr` is a TTY. Set
+ * `DEBUG_COLORS=no` or `false` to disable colors.
+ *
+ * @example
+ * ```ts
+ * const log = createDebug("hardhat:utils:foo");
+ * log("Starting up");
+ * log("Received %O", payload);
+ * log("Saved data", id, filePath);
+ *
+ * if (log.enabled) {
+ *   // expensive diagnostics that should only run while debugging
  * }
  * ```
+ *
+ * ```sh
+ * DEBUG="hardhat:*,-hardhat:noisy" DEBUG_COLORS=no pnpm hardhat run script.js
+ * ```
+ *
+ * @param namespace Namespace used for filtering and as the log prefix.
+ * @returns Logger function, or a shared no-op if disabled.
  */
-export function withDebugLogs(tag = "") {
-    return function actualDecorator(originalMethod, _context) {
-        const log = debugLib(`hardhat:dev:core${tag === "" ? "" : `:${tag}`}`);
-        function replacementMethod(...args) {
-            log(`Entering method with args:`, args);
-            const result = originalMethod.call(this, ...args);
-            log(`Exiting method.`);
-            return result;
-        }
-        return replacementMethod;
+export function createDebug(namespace) {
+    if (!isEnabled(namespace, process.env.DEBUG ?? "")) {
+        return NOOP;
+    }
+    const colors = useColors();
+    const color = colors ? selectColor(namespace) : undefined;
+    const prefix = color !== undefined
+        ? `\x1b[38;5;${color};1m  ${namespace}\x1b[0m`
+        : `  ${namespace}`;
+    const suffixOpen = color !== undefined ? `\x1b[38;5;${color}m` : "";
+    const suffixClose = color !== undefined ? `\x1b[0m` : "";
+    let prev = 0;
+    const logger = (format, ...args) => {
+        const now = Date.now();
+        const diff = prev === 0 ? 0 : now - prev;
+        prev = now;
+        const body = args.length === 0 && typeof format === "string"
+            ? format
+            : formatWithOptions({ colors }, format, ...args);
+        process.stderr.write(`${prefix} ${body} ${suffixOpen}+${diff}ms${suffixClose}\n`);
     };
+    return Object.assign(logger, { enabled: true });
 }
 //# sourceMappingURL=debug.js.map

package/dist/src/debug.js.map

@@ -1 +1 @@
-{"version":3,"file":"debug.js","sourceRoot":"","sources":["../../src/debug.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,OAAO,CAAC;AAE7B;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,aAAa,CAC3B,MAAc,EAAE;IAEhB,OAAO,SAAS,eAAe,CAC7B,cAAqD,EACrD,QAGC;QAED,MAAM,GAAG,GAAG,QAAQ,CAAC,mBAAmB,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,EAAE,CAAC,CAAC;QAEvE,SAAS,iBAAiB,CAAa,GAAG,IAAU;YAClD,GAAG,CAAC,4BAA4B,EAAE,IAAI,CAAC,CAAC;YACxC,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,CAAC;YAClD,GAAG,CAAC,iBAAiB,CAAC,CAAC;YACvB,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,OAAO,iBAAiB,CAAC;IAC3B,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"debug.js","sourceRoot":"","sources":["../../src/debug.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAE9C,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAW9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,UAAU,WAAW,CAAC,SAAiB;IAC3C,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE,CAAC;QACnD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;IAC3B,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC1D,MAAM,MAAM,GACV,KAAK,KAAK,SAAS;QACjB,CAAC,CAAC,aAAa,KAAK,QAAQ,SAAS,SAAS;QAC9C,CAAC,CAAC,KAAK,SAAS,EAAE,CAAC;IACvB,MAAM,UAAU,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,aAAa,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACpE,MAAM,WAAW,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;IACzD,IAAI,IAAI,GAAG,CAAC,CAAC;IAEb,MAAM,MAAM,GAAG,CAAC,MAAe,EAAE,GAAG,IAAe,EAAQ,EAAE;QAC3D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,IAAI,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC;QACzC,IAAI,GAAG,GAAG,CAAC;QAEX,MAAM,IAAI,GACR,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,MAAM,KAAK,QAAQ;YAC7C,CAAC,CAAC,MAAM;YACR,CAAC,CAAC,iBAAiB,CAAC,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC;QAErD,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,GAAG,MAAM,IAAI,IAAI,IAAI,UAAU,IAAI,IAAI,KAAK,WAAW,IAAI,CAC5D,CAAC;IACJ,CAAC,CAAC;IAEF,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;AAClD,CAAC"}

package/dist/src/fast-semver.d.ts

@@ -0,0 +1,49 @@
+/**
+ * A small, fast subset of semver: strict `MAJOR.MINOR.PATCH` parsing and
+ * triple-wise comparison helpers.
+ *
+ * This module exists because the full `semver` package is slow to load and is
+ * overkill for the many call sites in Hardhat that compare against hard-coded
+ * `x.y.z` literals. For range grammar (caret/tilde, disjunctions, prerelease
+ * subset, etc.) keep using `semver`.
+ */
+export type SemverVersion = [major: number, minor: number, patch: number];
+/**
+ * Parses a strict `MAJOR.MINOR.PATCH` version string into a `SemverVersion`
+ * tuple.
+ *
+ * An optional `+build` suffix is accepted and stripped silently. A
+ * `-prerelease` suffix is rejected.
+ *
+ * @param version The version string to parse.
+ * @returns The parsed `SemverVersion`, or `undefined` if the input does not
+ * match the strict `\d+\.\d+\.\d+` shape.
+ */
+export declare function parseVersion(version: string): SemverVersion | undefined;
+/**
+ * `Array#sort`-style comparator for `SemverVersion` tuples: returns a negative
+ * number, zero, or a positive number depending on whether `a` is lower than,
+ * equal to, or greater than `b`.
+ */
+export declare function compare(a: SemverVersion, b: SemverVersion): number;
+/**
+ * Returns `true` if `a` and `b` represent the same `MAJOR.MINOR.PATCH`.
+ */
+export declare function equals(a: SemverVersion, b: SemverVersion): boolean;
+/**
+ * Returns `true` if `compared` is strictly lower than `comparator`.
+ */
+export declare function lowerThan(compared: SemverVersion, comparator: SemverVersion): boolean;
+/**
+ * Returns `true` if `compared` is lower than or equal to `comparator`.
+ */
+export declare function lowerThanOrEqual(compared: SemverVersion, comparator: SemverVersion): boolean;
+/**
+ * Returns `true` if `compared` is strictly greater than `comparator`.
+ */
+export declare function greaterThan(compared: SemverVersion, comparator: SemverVersion): boolean;
+/**
+ * Returns `true` if `compared` is greater than or equal to `comparator`.
+ */
+export declare function greaterThanOrEqual(compared: SemverVersion, comparator: SemverVersion): boolean;
+//# sourceMappingURL=fast-semver.d.ts.map

package/dist/src/fast-semver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fast-semver.d.ts","sourceRoot":"","sources":["../../src/fast-semver.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;AAI1E;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAOvE;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,aAAa,GAAG,MAAM,CAQlE;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,aAAa,GAAG,OAAO,CAElE;AAED;;GAEG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,aAAa,EACvB,UAAU,EAAE,aAAa,GACxB,OAAO,CAET;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,aAAa,EACvB,UAAU,EAAE,aAAa,GACxB,OAAO,CAET;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,aAAa,EACvB,UAAU,EAAE,aAAa,GACxB,OAAO,CAET;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,aAAa,EACvB,UAAU,EAAE,aAAa,GACxB,OAAO,CAET"}

package/dist/src/fast-semver.js

@@ -0,0 +1,73 @@
+/**
+ * A small, fast subset of semver: strict `MAJOR.MINOR.PATCH` parsing and
+ * triple-wise comparison helpers.
+ *
+ * This module exists because the full `semver` package is slow to load and is
+ * overkill for the many call sites in Hardhat that compare against hard-coded
+ * `x.y.z` literals. For range grammar (caret/tilde, disjunctions, prerelease
+ * subset, etc.) keep using `semver`.
+ */
+const VERSION_REGEX = /^(\d+)\.(\d+)\.(\d+)(?:\+[0-9A-Za-z.-]+)?$/;
+/**
+ * Parses a strict `MAJOR.MINOR.PATCH` version string into a `SemverVersion`
+ * tuple.
+ *
+ * An optional `+build` suffix is accepted and stripped silently. A
+ * `-prerelease` suffix is rejected.
+ *
+ * @param version The version string to parse.
+ * @returns The parsed `SemverVersion`, or `undefined` if the input does not
+ * match the strict `\d+\.\d+\.\d+` shape.
+ */
+export function parseVersion(version) {
+    const match = VERSION_REGEX.exec(version);
+    if (match === null) {
+        return undefined;
+    }
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+/**
+ * `Array#sort`-style comparator for `SemverVersion` tuples: returns a negative
+ * number, zero, or a positive number depending on whether `a` is lower than,
+ * equal to, or greater than `b`.
+ */
+export function compare(a, b) {
+    if (a[0] !== b[0]) {
+        return a[0] - b[0];
+    }
+    if (a[1] !== b[1]) {
+        return a[1] - b[1];
+    }
+    return a[2] - b[2];
+}
+/**
+ * Returns `true` if `a` and `b` represent the same `MAJOR.MINOR.PATCH`.
+ */
+export function equals(a, b) {
+    return a[0] === b[0] && a[1] === b[1] && a[2] === b[2];
+}
+/**
+ * Returns `true` if `compared` is strictly lower than `comparator`.
+ */
+export function lowerThan(compared, comparator) {
+    return compare(compared, comparator) < 0;
+}
+/**
+ * Returns `true` if `compared` is lower than or equal to `comparator`.
+ */
+export function lowerThanOrEqual(compared, comparator) {
+    return compare(compared, comparator) <= 0;
+}
+/**
+ * Returns `true` if `compared` is strictly greater than `comparator`.
+ */
+export function greaterThan(compared, comparator) {
+    return compare(compared, comparator) > 0;
+}
+/**
+ * Returns `true` if `compared` is greater than or equal to `comparator`.
+ */
+export function greaterThanOrEqual(compared, comparator) {
+    return compare(compared, comparator) >= 0;
+}
+//# sourceMappingURL=fast-semver.js.map

package/dist/src/fast-semver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fast-semver.js","sourceRoot":"","sources":["../../src/fast-semver.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,aAAa,GAAG,4CAA4C,CAAC;AAEnE;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC1C,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAChE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,CAAgB,EAAE,CAAgB;IACxD,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAClB,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACrB,CAAC;IACD,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAClB,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACrB,CAAC;IACD,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AACrB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,MAAM,CAAC,CAAgB,EAAE,CAAgB;IACvD,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACzD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS,CACvB,QAAuB,EACvB,UAAyB;IAEzB,OAAO,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC;AAC3C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAC9B,QAAuB,EACvB,UAAyB;IAEzB,OAAO,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC;AAC5C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CACzB,QAAuB,EACvB,UAAyB;IAEzB,OAAO,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC;AAC3C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAAuB,EACvB,UAAyB;IAEzB,OAAO,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC;AAC5C,CAAC"}

package/dist/src/fs.d.ts

@@ -1,3 +1,49 @@
+/**
+ * Resolves paths to their true (on-disk) casing, caching directory listings
+ * and resolutions so repeated lookups against the same directories don't re-hit
+ * the filesystem.
+ *
+ * Intended to be used in hot paths where the same `from` directories are seen
+ * over and over.
+ *
+ * Does not resolve symbolic links.
+ *
+ * This class caches successful resolutions internally, and may do some
+ * duplicate work when multiple concurrent lookups for the same path are made
+ * before the first one finishes. It does not cache failed resolutions as
+ * negative result entries, but it does cache directory listings, so filesystem
+ * changes may not be observed until `clear()` is called. After `clear()`,
+ * previously cached directory and resolution data is discarded. If profiling
+ * shows that this work duplication is a problem, we can either cache in-flight
+ * operations, or add a mutex.
+ */
+export declare class TrueCasePathResolver {
+    #private;
+    /**
+     * Determines the true-case path of a given relative path from a specified
+     * directory, without resolving symbolic links.
+     *
+     * Note that the casing of the `from` path is not checked against the
+     * filesystem, and is trusted as-is. This avoids unnecessary directory
+     * listings for every ancestor of `from`, which can result in permission
+     * errors for directories that are otherwise accessible.
+     *
+     * @param from The absolute path of the directory to start the search from.
+     * @param relativePath The relative path to get the true case of.
+     * @returns The true case of the relative path. Returns an empty string if
+     * relativePath points to from.
+     * @throws FileNotFoundError if the starting directory or the relative path
+     *  doesn't exist or is ambiguous.
+     * @throws NotADirectoryError if the starting directory, or an intermediate
+     *  segment, is not a directory.
+     * @throws FileSystemAccessError for any other error.
+     */
+    getFileTrueCase(from: string, relativePath: string): Promise<string>;
+    /**
+     * Clears all cached directory listings and resolutions.
+     */
+    clear(): void;
+}
 /**
  * Determines the canonical pathname for a given path, resolving any symbolic
  * links, and returns it.
@@ -46,6 +92,7 @@ export declare function getAllDirectoriesMatching(dirFrom: string, matches?: (ab
  * @throws FileNotFoundError if the starting directory or the relative path doesn't exist.
  * @throws NotADirectoryError if the starting directory is not a directory.
  * @throws FileSystemAccessError for any other error.
+ * @deprecated Use {@link TrueCasePathResolver} instead.
  */
 export declare function getFileTrueCase(from: string, relativePath: string): Promise<string>;
 /**

package/dist/src/fs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../src/fs.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../src/fs.ts"],"names":[],"mappings":"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"}

package/dist/src/fs.js

@@ -7,6 +7,187 @@ import { JsonStreamStringify } from "json-stream-stringify";
 import { ensureError, ensureNodeErrnoExceptionError } from "./error.js";
 import { FileNotFoundError, FileSystemAccessError, InvalidFileFormatError, JsonSerializationError, FileAlreadyExistsError, NotADirectoryError, IsDirectoryError, DirectoryNotEmptyError, } from "./errors/fs.js";
 import { isDirectoryDirentAware, readdirWithFileTypesOrEmpty, } from "./internal/fs.js";
+const AMBIGUOUS_CASING_DIR_ENTRY = Symbol("ambiguous");
+/**
+ * Resolves paths to their true (on-disk) casing, caching directory listings
+ * and resolutions so repeated lookups against the same directories don't re-hit
+ * the filesystem.
+ *
+ * Intended to be used in hot paths where the same `from` directories are seen
+ * over and over.
+ *
+ * Does not resolve symbolic links.
+ *
+ * This class caches successful resolutions internally, and may do some
+ * duplicate work when multiple concurrent lookups for the same path are made
+ * before the first one finishes. It does not cache failed resolutions as
+ * negative result entries, but it does cache directory listings, so filesystem
+ * changes may not be observed until `clear()` is called. After `clear()`,
+ * previously cached directory and resolution data is discarded. If profiling
+ * shows that this work duplication is a problem, we can either cache in-flight
+ * operations, or add a mutex.
+ */
+export class TrueCasePathResolver {
+    /**
+     * A cache of DirEntries for the directories we've seen, keyed by their
+     * normalized absolute path as read. For example, if the same physical
+     * directory is read as `/a/foo` and `/a/Foo`, each path gets its own entry.
+     */
+    #dirCache = new Map();
+    /**
+     * A cache of successful resolutions, grouped by their `from` trusted starting
+     * directory.
+     *
+     * The outer key is the normalized absolute `from` path, and the inner key is
+     * the normalized `relativePath`.
+     *
+     * This keeps paths like `/a/B` + `foo.ts` distinct from `/a` + `B/foo.ts`,
+     * even if they point to the same location.
+     */
+    #resultCache = new Map();
+    /**
+     * Determines the true-case path of a given relative path from a specified
+     * directory, without resolving symbolic links.
+     *
+     * Note that the casing of the `from` path is not checked against the
+     * filesystem, and is trusted as-is. This avoids unnecessary directory
+     * listings for every ancestor of `from`, which can result in permission
+     * errors for directories that are otherwise accessible.
+     *
+     * @param from The absolute path of the directory to start the search from.
+     * @param relativePath The relative path to get the true case of.
+     * @returns The true case of the relative path. Returns an empty string if
+     * relativePath points to from.
+     * @throws FileNotFoundError if the starting directory or the relative path
+     *  doesn't exist or is ambiguous.
+     * @throws NotADirectoryError if the starting directory, or an intermediate
+     *  segment, is not a directory.
+     * @throws FileSystemAccessError for any other error.
+     */
+    async getFileTrueCase(from, relativePath) {
+        const absoluteFrom = path.resolve(from);
+        if (path.normalize(relativePath) === ".") {
+            // There's no casing to resolve, but we still read `from` so that callers
+            // get the documented FileNotFoundError / NotADirectoryError if it
+            // doesn't exist or isn't a directory.
+            await this.#getDirEntries(absoluteFrom);
+            return "";
+        }
+        const resolved = await this.#resolveFrom(absoluteFrom, relativePath);
+        const resolvedRelativePath = path.relative(absoluteFrom, resolved);
+        if (resolvedRelativePath === ".." ||
+            resolvedRelativePath.startsWith(`..${path.sep}`) ||
+            path.isAbsolute(resolvedRelativePath)) {
+            throw new FileNotFoundError(path.resolve(absoluteFrom, relativePath));
+        }
+        return resolvedRelativePath;
+    }
+    /**
+     * Clears all cached directory listings and resolutions.
+     */
+    clear() {
+        this.#dirCache.clear();
+        this.#resultCache.clear();
+    }
+    async #resolveFrom(from, relativePath) {
+        const fromCacheKey = this.#getResultFromCacheKey(from);
+        const relativePathCacheKey = this.#getResultRelativePathCacheKey(relativePath);
+        const cached = this.#resultCache
+            .get(fromCacheKey)
+            ?.get(relativePathCacheKey);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const resolved = await this.#doResolveFrom(from, relativePath);
+        let resultsFromCache = this.#resultCache.get(fromCacheKey);
+        if (resultsFromCache === undefined) {
+            resultsFromCache = new Map();
+            this.#resultCache.set(fromCacheKey, resultsFromCache);
+        }
+        resultsFromCache.set(relativePathCacheKey, resolved);
+        return resolved;
+    }
+    async #doResolveFrom(from, relativePath) {
+        let currentPath = from;
+        const segments = path
+            .normalize(relativePath)
+            .split(path.sep)
+            .filter((s) => s.length > 0 || s === ".");
+        for (const requestedName of segments) {
+            if (requestedName === "..") {
+                currentPath = path.join(currentPath, requestedName);
+                continue;
+            }
+            const entries = await this.#getDirEntries(currentPath);
+            const actualName = this.#lookupChild(entries, requestedName);
+            if (actualName === undefined) {
+                throw new FileNotFoundError(path.resolve(from, relativePath));
+            }
+            currentPath = path.join(currentPath, actualName);
+        }
+        return currentPath;
+    }
+    async #getDirEntries(dirPath) {
+        const cacheKey = this.#getDirCacheKey(dirPath);
+        const cached = this.#dirCache.get(cacheKey);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const entries = await this.#readDirEntries(dirPath);
+        this.#dirCache.set(cacheKey, entries);
+        return entries;
+    }
+    async #readDirEntries(dirPath) {
+        const names = await readdir(dirPath);
+        const exactNames = new Set();
+        const caseFoldedNames = new Map();
+        for (const name of names) {
+            exactNames.add(name);
+            const folded = this.#caseFold(name);
+            const previous = caseFoldedNames.get(folded);
+            if (previous === undefined) {
+                caseFoldedNames.set(folded, name);
+            }
+            else if (previous !== name) {
+                caseFoldedNames.set(folded, AMBIGUOUS_CASING_DIR_ENTRY);
+            }
+        }
+        return { exactNames, caseFoldedNames };
+    }
+    #lookupChild(entries, requestedName) {
+        if (entries.exactNames.has(requestedName)) {
+            return requestedName;
+        }
+        const candidate = entries.caseFoldedNames.get(this.#caseFold(requestedName));
+        if (candidate === undefined || candidate === AMBIGUOUS_CASING_DIR_ENTRY) {
+            return undefined;
+        }
+        return candidate;
+    }
+    #getResultFromCacheKey(from) {
+        return path.normalize(from);
+    }
+    #getResultRelativePathCacheKey(relativePath) {
+        return path.normalize(relativePath);
+    }
+    #getDirCacheKey(dirPath) {
+        return path.normalize(dirPath);
+    }
+    /**
+     * Returns a case-folded version of the given name, which can be thought of as
+     * a "normalized uppercase" form. This is used to implement case-insensitive
+     * comparisons.
+     *
+     * This is not an exact match with what every filesystem would do, but a good
+     * enough approximation for our purposes.
+     *
+     * @param name The name to fold.
+     * @returns The case-folded version of the name.
+     */
+    #caseFold(name) {
+        return name.normalize("NFC").toUpperCase();
+    }
+}
 /**
  * Determines the canonical pathname for a given path, resolving any symbolic
  * links, and returns it.
@@ -98,21 +279,10 @@ export async function getAllDirectoriesMatching(dirFrom, matches) {
  * @throws FileNotFoundError if the starting directory or the relative path doesn't exist.
  * @throws NotADirectoryError if the starting directory is not a directory.
  * @throws FileSystemAccessError for any other error.
+ * @deprecated Use {@link TrueCasePathResolver} instead.
  */
 export async function getFileTrueCase(from, relativePath) {
-    const dirEntries = await readdirOrEmpty(from);
-    const segments = relativePath.split(path.sep);
-    const nextDir = segments[0];
-    const nextDirLowerCase = nextDir.toLowerCase();
-    for (const dirEntry of dirEntries) {
-        if (dirEntry.toLowerCase() === nextDirLowerCase) {
-            if (segments.length === 1) {
-                return dirEntry;
-            }
-            return path.join(dirEntry, await getFileTrueCase(path.join(from, dirEntry), path.relative(nextDir, relativePath)));
-        }
-    }
-    throw new FileNotFoundError(path.join(from, relativePath));
+    return await new TrueCasePathResolver().getFileTrueCase(from, relativePath);
 }
 /**
  * Checks if a given path is a directory.