@nomicfoundation/hardhat-utils 4.0.5 → 4.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/dist/src/bytecode.d.ts +4 -0
  3. package/dist/src/bytecode.d.ts.map +1 -1
  4. package/dist/src/bytecode.js +12 -7
  5. package/dist/src/bytecode.js.map +1 -1
  6. package/dist/src/crypto.d.ts.map +1 -1
  7. package/dist/src/crypto.js +10 -2
  8. package/dist/src/crypto.js.map +1 -1
  9. package/dist/src/debug.d.ts +40 -8
  10. package/dist/src/debug.d.ts.map +1 -1
  11. package/dist/src/debug.js +54 -18
  12. package/dist/src/debug.js.map +1 -1
  13. package/dist/src/fast-semver.d.ts +49 -0
  14. package/dist/src/fast-semver.d.ts.map +1 -0
  15. package/dist/src/fast-semver.js +73 -0
  16. package/dist/src/fast-semver.js.map +1 -0
  17. package/dist/src/fs.d.ts +47 -0
  18. package/dist/src/fs.d.ts.map +1 -1
  19. package/dist/src/fs.js +204 -48
  20. package/dist/src/fs.js.map +1 -1
  21. package/dist/src/internal/bytecode.d.ts +11 -0
  22. package/dist/src/internal/bytecode.d.ts.map +1 -1
  23. package/dist/src/internal/bytecode.js +39 -2
  24. package/dist/src/internal/bytecode.js.map +1 -1
  25. package/dist/src/internal/debug.d.ts +35 -0
  26. package/dist/src/internal/debug.d.ts.map +1 -0
  27. package/dist/src/internal/debug.js +91 -0
  28. package/dist/src/internal/debug.js.map +1 -0
  29. package/dist/src/internal/fs.d.ts +15 -0
  30. package/dist/src/internal/fs.d.ts.map +1 -1
  31. package/dist/src/internal/fs.js +44 -0
  32. package/dist/src/internal/fs.js.map +1 -1
  33. package/dist/src/internal/global-dir.d.ts +2 -2
  34. package/dist/src/internal/global-dir.d.ts.map +1 -1
  35. package/dist/src/internal/global-dir.js +7 -1
  36. package/dist/src/internal/global-dir.js.map +1 -1
  37. package/dist/src/internal/lang.d.ts +3 -2
  38. package/dist/src/internal/lang.d.ts.map +1 -1
  39. package/dist/src/internal/lang.js +12 -6
  40. package/dist/src/internal/lang.js.map +1 -1
  41. package/dist/src/lang.js +2 -2
  42. package/dist/src/lang.js.map +1 -1
  43. package/dist/src/request.d.ts +11 -11
  44. package/dist/src/request.d.ts.map +1 -1
  45. package/dist/src/request.js +6 -6
  46. package/dist/src/request.js.map +1 -1
  47. package/dist/src/subprocess.d.ts +2 -0
  48. package/dist/src/subprocess.d.ts.map +1 -1
  49. package/dist/src/subprocess.js +1 -0
  50. package/dist/src/subprocess.js.map +1 -1
  51. package/dist/src/synchronization.d.ts +97 -0
  52. package/dist/src/synchronization.d.ts.map +1 -1
  53. package/dist/src/synchronization.js +177 -8
  54. package/dist/src/synchronization.js.map +1 -1
  55. package/package.json +3 -4
  56. package/src/bytecode.ts +15 -6
  57. package/src/crypto.ts +15 -2
  58. package/src/debug.ts +73 -28
  59. package/src/fast-semver.ts +95 -0
  60. package/src/fs.ts +282 -76
  61. package/src/internal/bytecode.ts +64 -5
  62. package/src/internal/debug.ts +119 -0
  63. package/src/internal/fs.ts +70 -0
  64. package/src/internal/global-dir.ts +10 -4
  65. package/src/internal/lang.ts +15 -6
  66. package/src/lang.ts +2 -2
  67. package/src/request.ts +16 -16
  68. package/src/subprocess.ts +2 -0
  69. package/src/synchronization.ts +217 -9
package/CHANGELOG.md CHANGED
@@ -1,5 +1,27 @@
1
1
  # @nomicfoundation/hardhat-utils
2
2
 
3
+ ## 4.1.1
4
+
5
+ ### Patch Changes
6
+
7
+ - [#8228](https://github.com/NomicFoundation/hardhat/pull/8228) [`417bbf9`](https://github.com/NomicFoundation/hardhat/commit/417bbf9f5d8ee4f9e19788aa40571452d36086d2) Thanks [@alcuadrado](https://github.com/alcuadrado)! - Small performance optimizations
8
+
9
+ ## 4.1.0
10
+
11
+ ### Minor Changes
12
+
13
+ - [#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
14
+
15
+ ### Patch Changes
16
+
17
+ - [#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.
18
+
19
+ - [#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
20
+
21
+ - [#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.
22
+
23
+ - [#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
24
+
3
25
  ## 4.0.5
4
26
 
5
27
  ### Patch Changes
@@ -19,6 +19,10 @@ export declare function resolveLinkedBytecode(artifact: Artifact, providedLibrar
19
19
  * Links the bytecode of a contract artifact with the provided library addresses.
20
20
  * This function does not perform any validation on the provided libraries.
21
21
  *
22
+ * Callers are responsible for ensuring that `libraries` contains no duplicate
23
+ * `(sourceName, libraryName)` entries; supplying duplicates would result in
24
+ * malformed bytecode.
25
+ *
22
26
  * @param artifact The contract artifact containing the bytecode and link references.
23
27
  * @param libraries An array of LibraryLink objects representing the libraries to be linked.
24
28
  * @returns The linked bytecode with all provided libraries correctly linked.
@@ -1 +1 @@
1
- {"version":3,"file":"bytecode.d.ts","sourceRoot":"","sources":["../../src/bytecode.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAClD,OAAO,KAAK,EACV,QAAQ,EACR,gBAAgB,EAChB,WAAW,EACZ,MAAM,wBAAwB,CAAC;AAUhC;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,QAAQ,EAClB,iBAAiB,EAAE,gBAAgB,GAClC,iBAAiB,CA0BnB;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,WAAW,EAAE,GACvB,iBAAiB,CAkBnB"}
1
+ {"version":3,"file":"bytecode.d.ts","sourceRoot":"","sources":["../../src/bytecode.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAClD,OAAO,KAAK,EACV,QAAQ,EAER,gBAAgB,EAChB,WAAW,EACZ,MAAM,wBAAwB,CAAC;AAWhC;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,QAAQ,EAClB,iBAAiB,EAAE,gBAAgB,GAClC,iBAAiB,CA0BnB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,WAAW,EAAE,GACvB,iBAAiB,CAqBnB"}
@@ -1,5 +1,5 @@
1
1
  import { getPrefixedHexString, getUnprefixedHexString } from "./hex.js";
2
- import { checkAmbiguousOrUnnecessaryLinks, checkMissingLibraryAddresses, checkOverlappingLibraryNames, checkProvidedLibraryAddresses, } from "./internal/bytecode.js";
2
+ import { applyBytecodeReplacements, checkAmbiguousOrUnnecessaryLinks, checkMissingLibraryAddresses, checkOverlappingLibraryNames, checkProvidedLibraryAddresses, } from "./internal/bytecode.js";
3
3
  /**
4
4
  * Resolves the linked bytecode for a given contract artifact by substituting
5
5
  * the required library placeholders within the bytecode with the provided
@@ -38,23 +38,28 @@ export function resolveLinkedBytecode(artifact, providedLibraries) {
38
38
  * Links the bytecode of a contract artifact with the provided library addresses.
39
39
  * This function does not perform any validation on the provided libraries.
40
40
  *
41
+ * Callers are responsible for ensuring that `libraries` contains no duplicate
42
+ * `(sourceName, libraryName)` entries; supplying duplicates would result in
43
+ * malformed bytecode.
44
+ *
41
45
  * @param artifact The contract artifact containing the bytecode and link references.
42
46
  * @param libraries An array of LibraryLink objects representing the libraries to be linked.
43
47
  * @returns The linked bytecode with all provided libraries correctly linked.
44
48
  */
45
49
  export function linkBytecode(artifact, libraries) {
46
50
  const { bytecode, linkReferences } = artifact;
47
- let linkedBytecode = bytecode;
51
+ const replacements = [];
48
52
  for (const { sourceName, libraryName, address } of libraries) {
49
53
  const contractLinkReferences = linkReferences[sourceName]?.[libraryName] ?? [];
50
54
  const unprefixedAddress = getUnprefixedHexString(address);
51
55
  for (const { start, length } of contractLinkReferences) {
52
- linkedBytecode =
53
- linkedBytecode.substring(0, 2 + start * 2) +
54
- unprefixedAddress +
55
- linkedBytecode.substring(2 + (start + length) * 2);
56
+ replacements.push({
57
+ start: 2 + start * 2,
58
+ length: length * 2,
59
+ value: unprefixedAddress,
60
+ });
56
61
  }
57
62
  }
58
- return getPrefixedHexString(linkedBytecode);
63
+ return getPrefixedHexString(applyBytecodeReplacements(bytecode, replacements));
59
64
  }
60
65
  //# sourceMappingURL=bytecode.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"bytecode.js","sourceRoot":"","sources":["../../src/bytecode.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AACxE,OAAO,EACL,gCAAgC,EAChC,4BAA4B,EAC5B,4BAA4B,EAC5B,6BAA6B,GAC9B,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,qBAAqB,CACnC,QAAkB,EAClB,iBAAmC;IAEnC,6BAA6B,CAAC,iBAAiB,CAAC,CAAC;IAEjD,MAAM,eAAe,GAAkB,EAAE,CAAC;IAC1C,KAAK,MAAM,CAAC,UAAU,EAAE,eAAe,CAAC,IAAI,MAAM,CAAC,OAAO,CACxD,QAAQ,CAAC,cAAc,CACxB,EAAE,CAAC;QACF,KAAK,MAAM,WAAW,IAAI,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC;YACvD,MAAM,UAAU,GAAG,GAAG,UAAU,IAAI,WAAW,EAAE,CAAC;YAClD,MAAM,OAAO,GACX,iBAAiB,CAAC,UAAU,CAAC,IAAI,iBAAiB,CAAC,WAAW,CAAC,CAAC;YAElE,eAAe,CAAC,IAAI,CAAC;gBACnB,UAAU;gBACV,WAAW;gBACX,UAAU;gBACV,OAAO;aACR,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,gCAAgC,CAAC,iBAAiB,EAAE,eAAe,CAAC,CAAC;IACrE,4BAA4B,CAAC,iBAAiB,EAAE,eAAe,CAAC,CAAC;IACjE,4BAA4B,CAAC,eAAe,CAAC,CAAC;IAE9C,OAAO,YAAY,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAC1B,QAAkB,EAClB,SAAwB;IAExB,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,QAAQ,CAAC;IAC9C,IAAI,cAAc,GAAG,QAAQ,CAAC;IAE9B,KAAK,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,SAAS,EAAE,CAAC;QAC7D,MAAM,sBAAsB,GAC1B,cAAc,CAAC,UAAU,CAAC,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC;QAClD,MAAM,iBAAiB,GAAG,sBAAsB,CAAC,OAAO,CAAC,CAAC;QAE1D,KAAK,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,sBAAsB,EAAE,CAAC;YACvD,cAAc;gBACZ,cAAc,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;oBAC1C,iBAAiB;oBACjB,cAAc,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;IAED,OAAO,oBAAoB,CAAC,cAAc,CAAC,CAAC;AAC9C,CAAC"}
1
+ {"version":3,"file":"bytecode.js","sourceRoot":"","sources":["../../src/bytecode.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AACxE,OAAO,EACL,yBAAyB,EACzB,gCAAgC,EAChC,4BAA4B,EAC5B,4BAA4B,EAC5B,6BAA6B,GAC9B,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,qBAAqB,CACnC,QAAkB,EAClB,iBAAmC;IAEnC,6BAA6B,CAAC,iBAAiB,CAAC,CAAC;IAEjD,MAAM,eAAe,GAAkB,EAAE,CAAC;IAC1C,KAAK,MAAM,CAAC,UAAU,EAAE,eAAe,CAAC,IAAI,MAAM,CAAC,OAAO,CACxD,QAAQ,CAAC,cAAc,CACxB,EAAE,CAAC;QACF,KAAK,MAAM,WAAW,IAAI,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC;YACvD,MAAM,UAAU,GAAG,GAAG,UAAU,IAAI,WAAW,EAAE,CAAC;YAClD,MAAM,OAAO,GACX,iBAAiB,CAAC,UAAU,CAAC,IAAI,iBAAiB,CAAC,WAAW,CAAC,CAAC;YAElE,eAAe,CAAC,IAAI,CAAC;gBACnB,UAAU;gBACV,WAAW;gBACX,UAAU;gBACV,OAAO;aACR,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,gCAAgC,CAAC,iBAAiB,EAAE,eAAe,CAAC,CAAC;IACrE,4BAA4B,CAAC,iBAAiB,EAAE,eAAe,CAAC,CAAC;IACjE,4BAA4B,CAAC,eAAe,CAAC,CAAC;IAE9C,OAAO,YAAY,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,YAAY,CAC1B,QAAkB,EAClB,SAAwB;IAExB,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,QAAQ,CAAC;IAC9C,MAAM,YAAY,GAA0B,EAAE,CAAC;IAE/C,KAAK,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,SAAS,EAAE,CAAC;QAC7D,MAAM,sBAAsB,GAC1B,cAAc,CAAC,UAAU,CAAC,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC;QAClD,MAAM,iBAAiB,GAAG,sBAAsB,CAAC,OAAO,CAAC,CAAC;QAE1D,KAAK,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,sBAAsB,EAAE,CAAC;YACvD,YAAY,CAAC,IAAI,CAAC;gBAChB,KAAK,EAAE,CAAC,GAAG,KAAK,GAAG,CAAC;gBACpB,MAAM,EAAE,MAAM,GAAG,CAAC;gBAClB,KAAK,EAAE,iBAAiB;aACzB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,oBAAoB,CACzB,yBAAyB,CAAC,QAAQ,EAAE,YAAY,CAAC,CAClD,CAAC;AACJ,CAAC"}
@@ -1 +1 @@
1
- {"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../../src/crypto.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAEtE;AAED;;;;;GAKG;AACH,wBAAsB,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAEnE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,4BAA4B,CAChD,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,CAAC,CAIjB"}
1
+ {"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../../src/crypto.ts"],"names":[],"mappings":"AAQA;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAOtE;AAED;;;;;GAKG;AACH,wBAAsB,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAKnE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,4BAA4B,CAChD,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,CAAC,CAIjB"}
@@ -1,5 +1,7 @@
1
- import { keccak256 as keccak256Impl } from "ethereum-cryptography/keccak";
2
- import { sha256 as sha256Impl } from "ethereum-cryptography/sha256";
1
+ // We don't load ethereum-cryptography on startup because it's slow to
2
+ // initialize and this module is transitively imported from many places.
3
+ let keccak256Impl;
4
+ let sha256Impl;
3
5
  /**
4
6
  * Computes the Keccak-256 hash of the input bytes.
5
7
  *
@@ -7,6 +9,9 @@ import { sha256 as sha256Impl } from "ethereum-cryptography/sha256";
7
9
  * @returns The Keccak-256 hash of the input bytes.
8
10
  */
9
11
  export async function keccak256(bytes) {
12
+ if (keccak256Impl === undefined) {
13
+ ({ keccak256: keccak256Impl } = await import("ethereum-cryptography/keccak"));
14
+ }
10
15
  return keccak256Impl(bytes);
11
16
  }
12
17
  /**
@@ -16,6 +21,9 @@ export async function keccak256(bytes) {
16
21
  * @returns The SHA-256 hash of the input bytes.
17
22
  */
18
23
  export async function sha256(bytes) {
24
+ if (sha256Impl === undefined) {
25
+ ({ sha256: sha256Impl } = await import("ethereum-cryptography/sha256"));
26
+ }
19
27
  return sha256Impl(bytes);
20
28
  }
21
29
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"crypto.js","sourceRoot":"","sources":["../../src/crypto.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,IAAI,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC1E,OAAO,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAEpE;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,KAAiB;IAC/C,OAAO,aAAa,CAAC,KAAK,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,KAAiB;IAC5C,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAChD,IAAY;IAEZ,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC/C,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC5D,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC7C,CAAC"}
1
+ {"version":3,"file":"crypto.js","sourceRoot":"","sources":["../../src/crypto.ts"],"names":[],"mappings":"AAGA,sEAAsE;AACtE,wEAAwE;AACxE,IAAI,aAA2C,CAAC;AAChD,IAAI,UAAqC,CAAC;AAE1C;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,KAAiB;IAC/C,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;QAChC,CAAC,EAAE,SAAS,EAAE,aAAa,EAAE,GAAG,MAAM,MAAM,CAC1C,8BAA8B,CAC/B,CAAC,CAAC;IACL,CAAC;IACD,OAAO,aAAa,CAAC,KAAK,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,KAAiB;IAC5C,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,MAAM,CAAC,8BAA8B,CAAC,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAChD,IAAY;IAEZ,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC/C,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC5D,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC7C,CAAC"}
@@ -1,16 +1,48 @@
1
1
  /**
2
- * A simple decorator that adds debug logging for when a method is entered and exited.
2
+ * A logger function returned by {@link createDebug}.
3
+ * The `enabled` property is `true` when the logger will produce output.
4
+ */
5
+ export interface DebugLogger {
6
+ (format: unknown, ...args: unknown[]): void;
7
+ readonly enabled: boolean;
8
+ }
9
+ /**
10
+ * Creates a namespaced logger controlled by the `DEBUG` env var.
3
11
  *
4
- * This decorator is meant to be used for debugging purposes only. It should not be committed in runtime code.
12
+ * If `namespace` matches `DEBUG`, the logger writes to `process.stderr`;
13
+ * otherwise, it is a no-op. Additionally, `logger.enabled` is `true` when
14
+ * the namespace matches `DEBUG`, allowing you to conditionally run expensive
15
+ * diagnostics.
5
16
  *
6
- * Example usage:
17
+ * `DEBUG` should be a comma- or whitespace-separated list of patterns.
18
+ * `*` is a wildcard and a leading `-` negates a pattern (e.g.
19
+ * `hardhat:*,-hardhat:noisy`).
7
20
  *
8
- * ```
9
- * class MyClass {
10
- * @withDebugLogs("MyClass:exampleClassMethod")
11
- * public function exampleClassMethod(...)
21
+ * Messages are formatted using `node:util.format`, allowing you to use format
22
+ * specifiers like `%O`, `%o`, `%s`, `%d`, `%j`. Extra arguments without a
23
+ * matching specifier are inspected automatically.
24
+ *
25
+ * Output is colorized per namespace when `stderr` is a TTY. Set
26
+ * `DEBUG_COLORS=no` or `false` to disable colors.
27
+ *
28
+ * @example
29
+ * ```ts
30
+ * const log = createDebug("hardhat:utils:foo");
31
+ * log("Starting up");
32
+ * log("Received %O", payload);
33
+ * log("Saved data", id, filePath);
34
+ *
35
+ * if (log.enabled) {
36
+ * // expensive diagnostics that should only run while debugging
12
37
  * }
13
38
  * ```
39
+ *
40
+ * ```sh
41
+ * DEBUG="hardhat:*,-hardhat:noisy" DEBUG_COLORS=no pnpm hardhat run script.js
42
+ * ```
43
+ *
44
+ * @param namespace Namespace used for filtering and as the log prefix.
45
+ * @returns Logger function, or a shared no-op if disabled.
14
46
  */
15
- 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;
47
+ export declare function createDebug(namespace: string): DebugLogger;
16
48
  //# sourceMappingURL=debug.d.ts.map
@@ -1 +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"}
1
+ {"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 CHANGED
@@ -1,28 +1,64 @@
1
- import debugLib from "debug";
1
+ import { formatWithOptions } from "node:util";
2
+ import { NOOP, isEnabled, selectColor, useColors } from "./internal/debug.js";
2
3
  /**
3
- * A simple decorator that adds debug logging for when a method is entered and exited.
4
+ * Creates a namespaced logger controlled by the `DEBUG` env var.
4
5
  *
5
- * This decorator is meant to be used for debugging purposes only. It should not be committed in runtime code.
6
+ * If `namespace` matches `DEBUG`, the logger writes to `process.stderr`;
7
+ * otherwise, it is a no-op. Additionally, `logger.enabled` is `true` when
8
+ * the namespace matches `DEBUG`, allowing you to conditionally run expensive
9
+ * diagnostics.
6
10
  *
7
- * Example usage:
11
+ * `DEBUG` should be a comma- or whitespace-separated list of patterns.
12
+ * `*` is a wildcard and a leading `-` negates a pattern (e.g.
13
+ * `hardhat:*,-hardhat:noisy`).
8
14
  *
9
- * ```
10
- * class MyClass {
11
- * @withDebugLogs("MyClass:exampleClassMethod")
12
- * public function exampleClassMethod(...)
15
+ * Messages are formatted using `node:util.format`, allowing you to use format
16
+ * specifiers like `%O`, `%o`, `%s`, `%d`, `%j`. Extra arguments without a
17
+ * matching specifier are inspected automatically.
18
+ *
19
+ * Output is colorized per namespace when `stderr` is a TTY. Set
20
+ * `DEBUG_COLORS=no` or `false` to disable colors.
21
+ *
22
+ * @example
23
+ * ```ts
24
+ * const log = createDebug("hardhat:utils:foo");
25
+ * log("Starting up");
26
+ * log("Received %O", payload);
27
+ * log("Saved data", id, filePath);
28
+ *
29
+ * if (log.enabled) {
30
+ * // expensive diagnostics that should only run while debugging
13
31
  * }
14
32
  * ```
33
+ *
34
+ * ```sh
35
+ * DEBUG="hardhat:*,-hardhat:noisy" DEBUG_COLORS=no pnpm hardhat run script.js
36
+ * ```
37
+ *
38
+ * @param namespace Namespace used for filtering and as the log prefix.
39
+ * @returns Logger function, or a shared no-op if disabled.
15
40
  */
16
- export function withDebugLogs(tag = "") {
17
- return function actualDecorator(originalMethod, _context) {
18
- const log = debugLib(`hardhat:dev:core${tag === "" ? "" : `:${tag}`}`);
19
- function replacementMethod(...args) {
20
- log(`Entering method with args:`, args);
21
- const result = originalMethod.call(this, ...args);
22
- log(`Exiting method.`);
23
- return result;
24
- }
25
- return replacementMethod;
41
+ export function createDebug(namespace) {
42
+ if (!isEnabled(namespace, process.env.DEBUG ?? "")) {
43
+ return NOOP;
44
+ }
45
+ const colors = useColors();
46
+ const color = colors ? selectColor(namespace) : undefined;
47
+ const prefix = color !== undefined
48
+ ? `\x1b[38;5;${color};1m ${namespace}\x1b[0m`
49
+ : ` ${namespace}`;
50
+ const suffixOpen = color !== undefined ? `\x1b[38;5;${color}m` : "";
51
+ const suffixClose = color !== undefined ? `\x1b[0m` : "";
52
+ let prev = 0;
53
+ const logger = (format, ...args) => {
54
+ const now = Date.now();
55
+ const diff = prev === 0 ? 0 : now - prev;
56
+ prev = now;
57
+ const body = args.length === 0 && typeof format === "string"
58
+ ? format
59
+ : formatWithOptions({ colors }, format, ...args);
60
+ process.stderr.write(`${prefix} ${body} ${suffixOpen}+${diff}ms${suffixClose}\n`);
26
61
  };
62
+ return Object.assign(logger, { enabled: true });
27
63
  }
28
64
  //# sourceMappingURL=debug.js.map
@@ -1 +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"}
1
+ {"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"}
@@ -0,0 +1,49 @@
1
+ /**
2
+ * A small, fast subset of semver: strict `MAJOR.MINOR.PATCH` parsing and
3
+ * triple-wise comparison helpers.
4
+ *
5
+ * This module exists because the full `semver` package is slow to load and is
6
+ * overkill for the many call sites in Hardhat that compare against hard-coded
7
+ * `x.y.z` literals. For range grammar (caret/tilde, disjunctions, prerelease
8
+ * subset, etc.) keep using `semver`.
9
+ */
10
+ export type SemverVersion = [major: number, minor: number, patch: number];
11
+ /**
12
+ * Parses a strict `MAJOR.MINOR.PATCH` version string into a `SemverVersion`
13
+ * tuple.
14
+ *
15
+ * An optional `+build` suffix is accepted and stripped silently. A
16
+ * `-prerelease` suffix is rejected.
17
+ *
18
+ * @param version The version string to parse.
19
+ * @returns The parsed `SemverVersion`, or `undefined` if the input does not
20
+ * match the strict `\d+\.\d+\.\d+` shape.
21
+ */
22
+ export declare function parseVersion(version: string): SemverVersion | undefined;
23
+ /**
24
+ * `Array#sort`-style comparator for `SemverVersion` tuples: returns a negative
25
+ * number, zero, or a positive number depending on whether `a` is lower than,
26
+ * equal to, or greater than `b`.
27
+ */
28
+ export declare function compare(a: SemverVersion, b: SemverVersion): number;
29
+ /**
30
+ * Returns `true` if `a` and `b` represent the same `MAJOR.MINOR.PATCH`.
31
+ */
32
+ export declare function equals(a: SemverVersion, b: SemverVersion): boolean;
33
+ /**
34
+ * Returns `true` if `compared` is strictly lower than `comparator`.
35
+ */
36
+ export declare function lowerThan(compared: SemverVersion, comparator: SemverVersion): boolean;
37
+ /**
38
+ * Returns `true` if `compared` is lower than or equal to `comparator`.
39
+ */
40
+ export declare function lowerThanOrEqual(compared: SemverVersion, comparator: SemverVersion): boolean;
41
+ /**
42
+ * Returns `true` if `compared` is strictly greater than `comparator`.
43
+ */
44
+ export declare function greaterThan(compared: SemverVersion, comparator: SemverVersion): boolean;
45
+ /**
46
+ * Returns `true` if `compared` is greater than or equal to `comparator`.
47
+ */
48
+ export declare function greaterThanOrEqual(compared: SemverVersion, comparator: SemverVersion): boolean;
49
+ //# sourceMappingURL=fast-semver.d.ts.map
@@ -0,0 +1 @@
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"}
@@ -0,0 +1,73 @@
1
+ /**
2
+ * A small, fast subset of semver: strict `MAJOR.MINOR.PATCH` parsing and
3
+ * triple-wise comparison helpers.
4
+ *
5
+ * This module exists because the full `semver` package is slow to load and is
6
+ * overkill for the many call sites in Hardhat that compare against hard-coded
7
+ * `x.y.z` literals. For range grammar (caret/tilde, disjunctions, prerelease
8
+ * subset, etc.) keep using `semver`.
9
+ */
10
+ const VERSION_REGEX = /^(\d+)\.(\d+)\.(\d+)(?:\+[0-9A-Za-z.-]+)?$/;
11
+ /**
12
+ * Parses a strict `MAJOR.MINOR.PATCH` version string into a `SemverVersion`
13
+ * tuple.
14
+ *
15
+ * An optional `+build` suffix is accepted and stripped silently. A
16
+ * `-prerelease` suffix is rejected.
17
+ *
18
+ * @param version The version string to parse.
19
+ * @returns The parsed `SemverVersion`, or `undefined` if the input does not
20
+ * match the strict `\d+\.\d+\.\d+` shape.
21
+ */
22
+ export function parseVersion(version) {
23
+ const match = VERSION_REGEX.exec(version);
24
+ if (match === null) {
25
+ return undefined;
26
+ }
27
+ return [Number(match[1]), Number(match[2]), Number(match[3])];
28
+ }
29
+ /**
30
+ * `Array#sort`-style comparator for `SemverVersion` tuples: returns a negative
31
+ * number, zero, or a positive number depending on whether `a` is lower than,
32
+ * equal to, or greater than `b`.
33
+ */
34
+ export function compare(a, b) {
35
+ if (a[0] !== b[0]) {
36
+ return a[0] - b[0];
37
+ }
38
+ if (a[1] !== b[1]) {
39
+ return a[1] - b[1];
40
+ }
41
+ return a[2] - b[2];
42
+ }
43
+ /**
44
+ * Returns `true` if `a` and `b` represent the same `MAJOR.MINOR.PATCH`.
45
+ */
46
+ export function equals(a, b) {
47
+ return a[0] === b[0] && a[1] === b[1] && a[2] === b[2];
48
+ }
49
+ /**
50
+ * Returns `true` if `compared` is strictly lower than `comparator`.
51
+ */
52
+ export function lowerThan(compared, comparator) {
53
+ return compare(compared, comparator) < 0;
54
+ }
55
+ /**
56
+ * Returns `true` if `compared` is lower than or equal to `comparator`.
57
+ */
58
+ export function lowerThanOrEqual(compared, comparator) {
59
+ return compare(compared, comparator) <= 0;
60
+ }
61
+ /**
62
+ * Returns `true` if `compared` is strictly greater than `comparator`.
63
+ */
64
+ export function greaterThan(compared, comparator) {
65
+ return compare(compared, comparator) > 0;
66
+ }
67
+ /**
68
+ * Returns `true` if `compared` is greater than or equal to `comparator`.
69
+ */
70
+ export function greaterThanOrEqual(compared, comparator) {
71
+ return compare(compared, comparator) >= 0;
72
+ }
73
+ //# sourceMappingURL=fast-semver.js.map
@@ -0,0 +1 @@
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 CHANGED
@@ -1,3 +1,49 @@
1
+ /**
2
+ * Resolves paths to their true (on-disk) casing, caching directory listings
3
+ * and resolutions so repeated lookups against the same directories don't re-hit
4
+ * the filesystem.
5
+ *
6
+ * Intended to be used in hot paths where the same `from` directories are seen
7
+ * over and over.
8
+ *
9
+ * Does not resolve symbolic links.
10
+ *
11
+ * This class caches successful resolutions internally, and may do some
12
+ * duplicate work when multiple concurrent lookups for the same path are made
13
+ * before the first one finishes. It does not cache failed resolutions as
14
+ * negative result entries, but it does cache directory listings, so filesystem
15
+ * changes may not be observed until `clear()` is called. After `clear()`,
16
+ * previously cached directory and resolution data is discarded. If profiling
17
+ * shows that this work duplication is a problem, we can either cache in-flight
18
+ * operations, or add a mutex.
19
+ */
20
+ export declare class TrueCasePathResolver {
21
+ #private;
22
+ /**
23
+ * Determines the true-case path of a given relative path from a specified
24
+ * directory, without resolving symbolic links.
25
+ *
26
+ * Note that the casing of the `from` path is not checked against the
27
+ * filesystem, and is trusted as-is. This avoids unnecessary directory
28
+ * listings for every ancestor of `from`, which can result in permission
29
+ * errors for directories that are otherwise accessible.
30
+ *
31
+ * @param from The absolute path of the directory to start the search from.
32
+ * @param relativePath The relative path to get the true case of.
33
+ * @returns The true case of the relative path. Returns an empty string if
34
+ * relativePath points to from.
35
+ * @throws FileNotFoundError if the starting directory or the relative path
36
+ * doesn't exist or is ambiguous.
37
+ * @throws NotADirectoryError if the starting directory, or an intermediate
38
+ * segment, is not a directory.
39
+ * @throws FileSystemAccessError for any other error.
40
+ */
41
+ getFileTrueCase(from: string, relativePath: string): Promise<string>;
42
+ /**
43
+ * Clears all cached directory listings and resolutions.
44
+ */
45
+ clear(): void;
46
+ }
1
47
  /**
2
48
  * Determines the canonical pathname for a given path, resolving any symbolic
3
49
  * links, and returns it.
@@ -46,6 +92,7 @@ export declare function getAllDirectoriesMatching(dirFrom: string, matches?: (ab
46
92
  * @throws FileNotFoundError if the starting directory or the relative path doesn't exist.
47
93
  * @throws NotADirectoryError if the starting directory is not a directory.
48
94
  * @throws FileSystemAccessError for any other error.
95
+ * @deprecated Use {@link TrueCasePathResolver} instead.
49
96
  */
50
97
  export declare function getFileTrueCase(from: string, relativePath: string): Promise<string>;
51
98
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../src/fs.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../src/fs.ts"],"names":[],"mappings":"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"}