@nomicfoundation/hardhat-utils 4.0.4 → 4.1.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @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
+
+- [#8187](https://github.com/NomicFoundation/hardhat/pull/8187) [`8f6a418`](https://github.com/NomicFoundation/hardhat/commit/8f6a418203e78b699ca1a4d9b498d13a428e71f6) Thanks [@ChristopherDedominici](https://github.com/ChristopherDedominici)! - Improved the logic for handling `Node.js` versions that fall below the minimum requirement.
+
+- [#8180](https://github.com/NomicFoundation/hardhat/pull/8180) [`4122faa`](https://github.com/NomicFoundation/hardhat/commit/4122faa3da2b588d83f2c94574f04ae2abd2e723) Thanks [@alcuadrado](https://github.com/alcuadrado)! - Optimize file system traversal helpers
+
 ## 4.0.4
 
 ### 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>;
 /**
@@ -143,6 +190,16 @@ export declare function readBinaryFile(absolutePathToFile: string): Promise<Uint
  * @throws FileSystemAccessError for any other error.
  */
 export declare function readdir(absolutePathToDir: string): Promise<string[]>;
+/**
+ * Reads a directory and returns its content as an array of strings, returning
+ * an empty array if the directory doesn't exist.
+ *
+ * @param absolutePathToDir The path to the directory.
+ * @returns An array of strings with the names of the files and directories in the directory, and an empty array if the directory doesn't exist.
+ * @throws NotADirectoryError if the path is not a directory.
+ * @throws FileSystemAccessError for any other error.
+ */
+export declare function readdirOrEmpty(absolutePathToDir: string): Promise<string[]>;
 /**
  * Creates a directory and any necessary directories along the way. If the directory already exists,
  * nothing is done.

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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"}