| FazBrowse GitHub Viewer | Trending | | Home |
| Tools: [Download Repo ZIP] [Original HTTPS Page] |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -64,159 +64,6 @@ const require = createRequire(import.meta.url); | |||
| 64 | 64 | const siblingModule = require('./sibling-module'); | |
| 65 | 65 | ``` | |
| 66 | 66 | ||
| 67 | - ### `module.constants.compileCacheStatus` | ||
| 68 | - | ||
| 69 | - <!-- YAML | ||
| 70 | - added: v22.8.0 | ||
| 71 | - --> | ||
| 72 | - | ||
| 73 | - > Stability: 1.1 - Active Development | ||
| 74 | - | ||
| 75 | - The following constants are returned as the `status` field in the object returned by | ||
| 76 | - [`module.enableCompileCache()`][] to indicate the result of the attempt to enable the | ||
| 77 | - [module compile cache][]. | ||
| 78 | - | ||
| 79 | - <table> | ||
| 80 | - <tr> | ||
| 81 | - <th>Constant</th> | ||
| 82 | - <th>Description</th> | ||
| 83 | - </tr> | ||
| 84 | - <tr> | ||
| 85 | - <td><code>ENABLED</code></td> | ||
| 86 | - <td> | ||
| 87 | - Node.js has enabled the compile cache successfully. The directory used to store the | ||
| 88 | - compile cache will be returned in the <code>directory</code> field in the | ||
| 89 | - returned object. | ||
| 90 | - </td> | ||
| 91 | - </tr> | ||
| 92 | - <tr> | ||
| 93 | - <td><code>ALREADY_ENABLED</code></td> | ||
| 94 | - <td> | ||
| 95 | - The compile cache has already been enabled before, either by a previous call to | ||
| 96 | - <code>module.enableCompileCache()</code>, or by the <code>NODE_COMPILE_CACHE=dir</code> | ||
| 97 | - environment variable. The directory used to store the | ||
| 98 | - compile cache will be returned in the <code>directory</code> field in the | ||
| 99 | - returned object. | ||
| 100 | - </td> | ||
| 101 | - </tr> | ||
| 102 | - <tr> | ||
| 103 | - <td><code>FAILED</code></td> | ||
| 104 | - <td> | ||
| 105 | - Node.js fails to enable the compile cache. This can be caused by the lack of | ||
| 106 | - permission to use the specified directory, or various kinds of file system errors. | ||
| 107 | - The detail of the failure will be returned in the <code>message</code> field in the | ||
| 108 | - returned object. | ||
| 109 | - </td> | ||
| 110 | - </tr> | ||
| 111 | - <tr> | ||
| 112 | - <td><code>DISABLED</code></td> | ||
| 113 | - <td> | ||
| 114 | - Node.js cannot enable the compile cache because the environment variable | ||
| 115 | - <code>NODE_DISABLE_COMPILE_CACHE=1</code> has been set. | ||
| 116 | - </td> | ||
| 117 | - </tr> | ||
| 118 | - </table> | ||
| 119 | - | ||
| 120 | - ### `module.enableCompileCache([cacheDir])` | ||
| 121 | - | ||
| 122 | - <!-- YAML | ||
| 123 | - added: v22.8.0 | ||
| 124 | - --> | ||
| 125 | - | ||
| 126 | - > Stability: 1.1 - Active Development | ||
| 127 | - | ||
| 128 | - * `cacheDir` {string|undefined} Optional path to specify the directory where the compile cache | ||
| 129 | - will be stored/retrieved. | ||
| 130 | - * Returns: {Object} | ||
| 131 | - * `status` {integer} One of the [`module.constants.compileCacheStatus`][] | ||
| 132 | - * `message` {string|undefined} If Node.js cannot enable the compile cache, this contains | ||
| 133 | - the error message. Only set if `status` is `module.constants.compileCacheStatus.FAILED`. | ||
| 134 | - * `directory` {string|undefined} If the compile cache is enabled, this contains the directory | ||
| 135 | - where the compile cache is stored. Only set if `status` is | ||
| 136 | - `module.constants.compileCacheStatus.ENABLED` or | ||
| 137 | - `module.constants.compileCacheStatus.ALREADY_ENABLED`. | ||
| 138 | - | ||
| 139 | - Enable [module compile cache][] in the current Node.js instance. | ||
| 140 | - | ||
| 141 | - If `cacheDir` is not specified, Node.js will either use the directory specified by the | ||
| 142 | - [`NODE_COMPILE_CACHE=dir`][] environment variable if it's set, or use | ||
| 143 | - `path.join(os.tmpdir(), 'node-compile-cache')` otherwise. For general use cases, it's | ||
| 144 | - recommended to call `module.enableCompileCache()` without specifying the `cacheDir`, | ||
| 145 | - so that the directory can be overridden by the `NODE_COMPILE_CACHE` environment | ||
| 146 | - variable when necessary. | ||
| 147 | - | ||
| 148 | - Since compile cache is supposed to be a quiet optimization that is not required for the | ||
| 149 | - application to be functional, this method is designed to not throw any exception when the | ||
| 150 | - compile cache cannot be enabled. Instead, it will return an object containing an error | ||
| 151 | - message in the `message` field to aid debugging. | ||
| 152 | - If compile cache is enabled successfully, the `directory` field in the returned object | ||
| 153 | - contains the path to the directory where the compile cache is stored. The `status` | ||
| 154 | - field in the returned object would be one of the `module.constants.compileCacheStatus` | ||
| 155 | - values to indicate the result of the attempt to enable the [module compile cache][]. | ||
| 156 | - | ||
| 157 | - This method only affects the current Node.js instance. To enable it in child worker threads, | ||
| 158 | - either call this method in child worker threads too, or set the | ||
| 159 | - `process.env.NODE_COMPILE_CACHE` value to compile cache directory so the behavior can | ||
| 160 | - be inherited into the child workers. The directory can be obtained either from the | ||
| 161 | - `directory` field returned by this method, or with [`module.getCompileCacheDir()`][]. | ||
| 162 | - | ||
| 163 | - #### Module compile cache | ||
| 164 | - | ||
| 165 | - <!-- YAML | ||
| 166 | - added: v22.1.0 | ||
| 167 | - changes: | ||
| 168 | - - version: v22.8.0 | ||
| 169 | - pr-url: https://github.com/nodejs/node/pull/54501 | ||
| 170 | - description: add initial JavaScript APIs for runtime access. | ||
| 171 | - --> | ||
| 172 | - | ||
| 173 | - The module compile cache can be enabled either using the [`module.enableCompileCache()`][] | ||
| 174 | - method or the [`NODE_COMPILE_CACHE=dir`][] environment variable. After it is enabled, | ||
| 175 | - whenever Node.js compiles a CommonJS or a ECMAScript Module, it will use on-disk | ||
| 176 | - [V8 code cache][] persisted in the specified directory to speed up the compilation. | ||
| 177 | - This may slow down the first load of a module graph, but subsequent loads of the same module | ||
| 178 | - graph may get a significant speedup if the contents of the modules do not change. | ||
| 179 | - | ||
| 180 | - To clean up the generated compile cache on disk, simply remove the cache directory. The cache | ||
| 181 | - directory will be recreated the next time the same directory is used for for compile cache | ||
| 182 | - storage. To avoid filling up the disk with stale cache, it is recommended to use a directory | ||
| 183 | - under the [`os.tmpdir()`][]. If the compile cache is enabled by a call to | ||
| 184 | - [`module.enableCompileCache()`][] without specifying the directory, Node.js will use | ||
| 185 | - the [`NODE_COMPILE_CACHE=dir`][] environment variable if it's set, or defaults | ||
| 186 | - to `path.join(os.tmpdir(), 'node-compile-cache')` otherwise. To locate the compile cache | ||
| 187 | - directory used by a running Node.js instance, use [`module.getCompileCacheDir()`][]. | ||
| 188 | - | ||
| 189 | - Currently when using the compile cache with [V8 JavaScript code coverage][], the | ||
| 190 | - coverage being collected by V8 may be less precise in functions that are | ||
| 191 | - deserialized from the code cache. It's recommended to turn this off when | ||
| 192 | - running tests to generate precise coverage. | ||
| 193 | - | ||
| 194 | - The enabled module compile cache can be disabled by the [`NODE_DISABLE_COMPILE_CACHE=1`][] | ||
| 195 | - environment variable. This can be useful when the compile cache leads to unexpected or | ||
| 196 | - undesired behaviors (e.g. less precise test coverage). | ||
| 197 | - | ||
| 198 | - Compilation cache generated by one version of Node.js can not be reused by a different | ||
| 199 | - version of Node.js. Cache generated by different versions of Node.js will be stored | ||
| 200 | - separately if the same base directory is used to persist the cache, so they can co-exist. | ||
| 201 | - | ||
| 202 | - At the moment, when the compile cache is enabled and a module is loaded afresh, the | ||
| 203 | - code cache is generated from the compiled code immediately, but will only be written | ||
| 204 | - to disk when the Node.js instance is about to exit. This is subject to change. The | ||
| 205 | - [`module.flushCompileCache()`][] method can be used to ensure the accumulated code cache | ||
| 206 | - is flushed to disk in case the application wants to spawn other Node.js instances | ||
| 207 | - and let them share the cache long before the parent exits. | ||
| 208 | - | ||
| 209 | - ### `module.getCompileCacheDir()` | ||
| 210 | - | ||
| 211 | - <!-- YAML | ||
| 212 | - added: v22.8.0 | ||
| 213 | - --> | ||
| 214 | - | ||
| 215 | - > Stability: 1.1 - Active Development | ||
| 216 | - | ||
| 217 | - * Returns: {string|undefined} Path to the [module compile cache][] directory if it is enabled, | ||
| 218 | - or `undefined` otherwise. | ||
| 219 | - | ||
| 220 | 67 | ### `module.findPackageJSON(specifier[, base])` | |
| 221 | 68 | ||
| 222 | 69 | <!-- YAML | |
@@ -352,7 +199,7 @@ changes: | |||
| 352 | 199 | Register a module that exports [hooks][] that customize Node.js module | |
| 353 | 200 | resolution and loading behavior. See [Customization hooks][]. | |
| 354 | 201 | ||
| 355 | - ## `module.stripTypeScriptTypes(code[, options])` | ||
| 202 | + ### `module.stripTypeScriptTypes(code[, options])` | ||
| 356 | 203 | ||
| 357 | 204 | <!-- YAML | |
| 358 | 205 | added: v23.2.0 | |
@@ -490,6 +337,174 @@ import('node:fs').then((esmFS) => { | |||
| 490 | 337 | }); | |
| 491 | 338 | ``` | |
| 492 | 339 | ||
| 340 | + ## Module compile cache | ||
| 341 | + | ||
| 342 | + <!-- YAML | ||
| 343 | + added: v22.1.0 | ||
| 344 | + changes: | ||
| 345 | + - version: v22.8.0 | ||
| 346 | + pr-url: https://github.com/nodejs/node/pull/54501 | ||
| 347 | + description: add initial JavaScript APIs for runtime access. | ||
| 348 | + --> | ||
| 349 | + | ||
| 350 | + The module compile cache can be enabled either using the [`module.enableCompileCache()`][] | ||
| 351 | + method or the [`NODE_COMPILE_CACHE=dir`][] environment variable. After it is enabled, | ||
| 352 | + whenever Node.js compiles a CommonJS or a ECMAScript Module, it will use on-disk | ||
| 353 | + [V8 code cache][] persisted in the specified directory to speed up the compilation. | ||
| 354 | + This may slow down the first load of a module graph, but subsequent loads of the same module | ||
| 355 | + graph may get a significant speedup if the contents of the modules do not change. | ||
| 356 | + | ||
| 357 | + To clean up the generated compile cache on disk, simply remove the cache directory. The cache | ||
| 358 | + directory will be recreated the next time the same directory is used for for compile cache | ||
| 359 | + storage. To avoid filling up the disk with stale cache, it is recommended to use a directory | ||
| 360 | + under the [`os.tmpdir()`][]. If the compile cache is enabled by a call to | ||
| 361 | + [`module.enableCompileCache()`][] without specifying the directory, Node.js will use | ||
| 362 | + the [`NODE_COMPILE_CACHE=dir`][] environment variable if it's set, or defaults | ||
| 363 | + to `path.join(os.tmpdir(), 'node-compile-cache')` otherwise. To locate the compile cache | ||
| 364 | + directory used by a running Node.js instance, use [`module.getCompileCacheDir()`][]. | ||
| 365 | + | ||
| 366 | + Currently when using the compile cache with [V8 JavaScript code coverage][], the | ||
| 367 | + coverage being collected by V8 may be less precise in functions that are | ||
| 368 | + deserialized from the code cache. It's recommended to turn this off when | ||
| 369 | + running tests to generate precise coverage. | ||
| 370 | + | ||
| 371 | + The enabled module compile cache can be disabled by the [`NODE_DISABLE_COMPILE_CACHE=1`][] | ||
| 372 | + environment variable. This can be useful when the compile cache leads to unexpected or | ||
| 373 | + undesired behaviors (e.g. less precise test coverage). | ||
| 374 | + | ||
| 375 | + Compilation cache generated by one version of Node.js can not be reused by a different | ||
| 376 | + version of Node.js. Cache generated by different versions of Node.js will be stored | ||
| 377 | + separately if the same base directory is used to persist the cache, so they can co-exist. | ||
| 378 | + | ||
| 379 | + At the moment, when the compile cache is enabled and a module is loaded afresh, the | ||
| 380 | + code cache is generated from the compiled code immediately, but will only be written | ||
| 381 | + to disk when the Node.js instance is about to exit. This is subject to change. The | ||
| 382 | + [`module.flushCompileCache()`][] method can be used to ensure the accumulated code cache | ||
| 383 | + is flushed to disk in case the application wants to spawn other Node.js instances | ||
| 384 | + and let them share the cache long before the parent exits. | ||
| 385 | + | ||
| 386 | + ### `module.constants.compileCacheStatus` | ||
| 387 | + | ||
| 388 | + <!-- YAML | ||
| 389 | + added: v22.8.0 | ||
| 390 | + --> | ||
| 391 | + | ||
| 392 | + > Stability: 1.1 - Active Development | ||
| 393 | + | ||
| 394 | + The following constants are returned as the `status` field in the object returned by | ||
| 395 | + [`module.enableCompileCache()`][] to indicate the result of the attempt to enable the | ||
| 396 | + [module compile cache][]. | ||
| 397 | + | ||
| 398 | + <table> | ||
| 399 | + <tr> | ||
| 400 | + <th>Constant</th> | ||
| 401 | + <th>Description</th> | ||
| 402 | + </tr> | ||
| 403 | + <tr> | ||
| 404 | + <td><code>ENABLED</code></td> | ||
| 405 | + <td> | ||
| 406 | + Node.js has enabled the compile cache successfully. The directory used to store the | ||
| 407 | + compile cache will be returned in the <code>directory</code> field in the | ||
| 408 | + returned object. | ||
| 409 | + </td> | ||
| 410 | + </tr> | ||
| 411 | + <tr> | ||
| 412 | + <td><code>ALREADY_ENABLED</code></td> | ||
| 413 | + <td> | ||
| 414 | + The compile cache has already been enabled before, either by a previous call to | ||
| 415 | + <code>module.enableCompileCache()</code>, or by the <code>NODE_COMPILE_CACHE=dir</code> | ||
| 416 | + environment variable. The directory used to store the | ||
| 417 | + compile cache will be returned in the <code>directory</code> field in the | ||
| 418 | + returned object. | ||
| 419 | + </td> | ||
| 420 | + </tr> | ||
| 421 | + <tr> | ||
| 422 | + <td><code>FAILED</code></td> | ||
| 423 | + <td> | ||
| 424 | + Node.js fails to enable the compile cache. This can be caused by the lack of | ||
| 425 | + permission to use the specified directory, or various kinds of file system errors. | ||
| 426 | + The detail of the failure will be returned in the <code>message</code> field in the | ||
| 427 | + returned object. | ||
| 428 | + </td> | ||
| 429 | + </tr> | ||
| 430 | + <tr> | ||
| 431 | + <td><code>DISABLED</code></td> | ||
| 432 | + <td> | ||
| 433 | + Node.js cannot enable the compile cache because the environment variable | ||
| 434 | + <code>NODE_DISABLE_COMPILE_CACHE=1</code> has been set. | ||
| 435 | + </td> | ||
| 436 | + </tr> | ||
| 437 | + </table> | ||
| 438 | + | ||
| 439 | + ### `module.enableCompileCache([cacheDir])` | ||
| 440 | + | ||
| 441 | + <!-- YAML | ||
| 442 | + added: v22.8.0 | ||
| 443 | + --> | ||
| 444 | + | ||
| 445 | + > Stability: 1.1 - Active Development | ||
| 446 | + | ||
| 447 | + * `cacheDir` {string|undefined} Optional path to specify the directory where the compile cache | ||
| 448 | + will be stored/retrieved. | ||
| 449 | + * Returns: {Object} | ||
| 450 | + * `status` {integer} One of the [`module.constants.compileCacheStatus`][] | ||
| 451 | + * `message` {string|undefined} If Node.js cannot enable the compile cache, this contains | ||
| 452 | + the error message. Only set if `status` is `module.constants.compileCacheStatus.FAILED`. | ||
| 453 | + * `directory` {string|undefined} If the compile cache is enabled, this contains the directory | ||
| 454 | + where the compile cache is stored. Only set if `status` is | ||
| 455 | + `module.constants.compileCacheStatus.ENABLED` or | ||
| 456 | + `module.constants.compileCacheStatus.ALREADY_ENABLED`. | ||
| 457 | + | ||
| 458 | + Enable [module compile cache][] in the current Node.js instance. | ||
| 459 | + | ||
| 460 | + If `cacheDir` is not specified, Node.js will either use the directory specified by the | ||
| 461 | + [`NODE_COMPILE_CACHE=dir`][] environment variable if it's set, or use | ||
| 462 | + `path.join(os.tmpdir(), 'node-compile-cache')` otherwise. For general use cases, it's | ||
| 463 | + recommended to call `module.enableCompileCache()` without specifying the `cacheDir`, | ||
| 464 | + so that the directory can be overridden by the `NODE_COMPILE_CACHE` environment | ||
| 465 | + variable when necessary. | ||
| 466 | + | ||
| 467 | + Since compile cache is supposed to be a quiet optimization that is not required for the | ||
| 468 | + application to be functional, this method is designed to not throw any exception when the | ||
| 469 | + compile cache cannot be enabled. Instead, it will return an object containing an error | ||
| 470 | + message in the `message` field to aid debugging. | ||
| 471 | + If compile cache is enabled successfully, the `directory` field in the returned object | ||
| 472 | + contains the path to the directory where the compile cache is stored. The `status` | ||
| 473 | + field in the returned object would be one of the `module.constants.compileCacheStatus` | ||
| 474 | + values to indicate the result of the attempt to enable the [module compile cache][]. | ||
| 475 | + | ||
| 476 | + This method only affects the current Node.js instance. To enable it in child worker threads, | ||
| 477 | + either call this method in child worker threads too, or set the | ||
| 478 | + `process.env.NODE_COMPILE_CACHE` value to compile cache directory so the behavior can | ||
| 479 | + be inherited into the child workers. The directory can be obtained either from the | ||
| 480 | + `directory` field returned by this method, or with [`module.getCompileCacheDir()`][]. | ||
| 481 | + | ||
| 482 | + ### `module.flushCompileCache()` | ||
| 483 | + | ||
| 484 | + <!-- YAML | ||
| 485 | + added: | ||
| 486 | + - v23.0.0 | ||
| 487 | + --> | ||
| 488 | + | ||
| 489 | + > Stability: 1.1 - Active Development | ||
| 490 | + | ||
| 491 | + Flush the [module compile cache][] accumulated from modules already loaded | ||
| 492 | + in the current Node.js instance to disk. This returns after all the flushing | ||
| 493 | + file system operations come to an end, no matter they succeed or not. If there | ||
| 494 | + are any errors, this will fail silently, since compile cache misses should not | ||
| 495 | + interfere with the actual operation of the application. | ||
| 496 | + | ||
| 497 | + ### `module.getCompileCacheDir()` | ||
| 498 | + | ||
| 499 | + <!-- YAML | ||
| 500 | + added: v22.8.0 | ||
| 501 | + --> | ||
| 502 | + | ||
| 503 | + > Stability: 1.1 - Active Development | ||
| 504 | + | ||
| 505 | + * Returns: {string|undefined} Path to the [module compile cache][] directory if it is enabled, | ||
| 506 | + or `undefined` otherwise. | ||
| 507 | + | ||
| 493 | 508 | <i id="module_customization_hooks"></i> | |
| 494 | 509 | ||
| 495 | 510 | ## Customization Hooks | |
@@ -1285,21 +1300,6 @@ added: | |||
| 1285 | 1300 | `path` is the resolved path for the file for which a corresponding source map | |
| 1286 | 1301 | should be fetched. | |
| 1287 | 1302 | ||
| 1288 | - ### `module.flushCompileCache()` | ||
| 1289 | - | ||
| 1290 | - <!-- YAML | ||
| 1291 | - added: | ||
| 1292 | - - v23.0.0 | ||
| 1293 | - --> | ||
| 1294 | - | ||
| 1295 | - > Stability: 1.1 - Active Development | ||
| 1296 | - | ||
| 1297 | - Flush the [module compile cache][] accumulated from modules already loaded | ||
| 1298 | - in the current Node.js instance to disk. This returns after all the flushing | ||
| 1299 | - file system operations come to an end, no matter they succeed or not. If there | ||
| 1300 | - are any errors, this will fail silently, since compile cache misses should not | ||
| 1301 | - interfere with the actual operation of the application. | ||
| 1302 | - | ||
| 1303 | 1303 | ### Class: `module.SourceMap` | |
| 1304 | 1304 | ||
| 1305 | 1305 | <!-- YAML | |
| Back | FazBrowse Home | New Git URL |
0 commit comments