GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — doc: fix module.md headings · nodejs/node@b667cc4

File tree

Expand file treeCollapse file tree
Open diff view settings
Filter options
  • doc/api
    • module.md
Expand file treeCollapse file tree
Open diff view settings
Collapse file

‎doc/api/module.md‎

Copy file name to clipboardExpand all lines: doc/api/module.md
+170-16Lines changed: 170 additions & 16 deletions
  • Display the source diff
  • Display the rich diff
Original file line numberDiff line numberDiff line change
@@ -270,7 +270,7 @@ changes:
270270
Register a module that exports [hooks][] that customize Node.js module
271271
resolution and loading behavior. See [Customization hooks][].
272272
273-
## `module.stripTypeScriptTypes(code[, options])`
273+
### `module.stripTypeScriptTypes(code[, options])`
274274
275275
<!-- YAML
276276
added: REPLACEME
@@ -408,6 +408,175 @@ import('node:fs').then((esmFS) => {
408408
});
409409
```
410410
411+
## Module compile cache
412+
413+
<!-- YAML
414+
added: v22.1.0
415+
changes:
416+
- version: v22.8.0
417+
pr-url: https://github.com/nodejs/node/pull/54501
418+
description: add initial JavaScript APIs for runtime access.
419+
-->
420+
421+
The module compile cache can be enabled either using the [`module.enableCompileCache()`][]
422+
method or the [`NODE_COMPILE_CACHE=dir`][] environment variable. After it is enabled,
423+
whenever Node.js compiles a CommonJS or a ECMAScript Module, it will use on-disk
424+
[V8 code cache][] persisted in the specified directory to speed up the compilation.
425+
This may slow down the first load of a module graph, but subsequent loads of the same module
426+
graph may get a significant speedup if the contents of the modules do not change.
427+
428+
To clean up the generated compile cache on disk, simply remove the cache directory. The cache
429+
directory will be recreated the next time the same directory is used for for compile cache
430+
storage. To avoid filling up the disk with stale cache, it is recommended to use a directory
431+
under the [`os.tmpdir()`][]. If the compile cache is enabled by a call to
432+
[`module.enableCompileCache()`][] without specifying the directory, Node.js will use
433+
the [`NODE_COMPILE_CACHE=dir`][] environment variable if it's set, or defaults
434+
to `path.join(os.tmpdir(), 'node-compile-cache')` otherwise. To locate the compile cache
435+
directory used by a running Node.js instance, use [`module.getCompileCacheDir()`][].
436+
437+
Currently when using the compile cache with [V8 JavaScript code coverage][], the
438+
coverage being collected by V8 may be less precise in functions that are
439+
deserialized from the code cache. It's recommended to turn this off when
440+
running tests to generate precise coverage.
441+
442+
The enabled module compile cache can be disabled by the [`NODE_DISABLE_COMPILE_CACHE=1`][]
443+
environment variable. This can be useful when the compile cache leads to unexpected or
444+
undesired behaviors (e.g. less precise test coverage).
445+
446+
Compilation cache generated by one version of Node.js can not be reused by a different
447+
version of Node.js. Cache generated by different versions of Node.js will be stored
448+
separately if the same base directory is used to persist the cache, so they can co-exist.
449+
450+
At the moment, when the compile cache is enabled and a module is loaded afresh, the
451+
code cache is generated from the compiled code immediately, but will only be written
452+
to disk when the Node.js instance is about to exit. This is subject to change. The
453+
[`module.flushCompileCache()`][] method can be used to ensure the accumulated code cache
454+
is flushed to disk in case the application wants to spawn other Node.js instances
455+
and let them share the cache long before the parent exits.
456+
457+
### `module.constants.compileCacheStatus`
458+
459+
<!-- YAML
460+
added: v22.8.0
461+
-->
462+
463+
> Stability: 1.1 - Active Development
464+
465+
The following constants are returned as the `status` field in the object returned by
466+
[`module.enableCompileCache()`][] to indicate the result of the attempt to enable the
467+
[module compile cache][].
468+
469+
<table>
470+
<tr>
471+
<th>Constant</th>
472+
<th>Description</th>
473+
</tr>
474+
<tr>
475+
<td><code>ENABLED</code></td>
476+
<td>
477+
Node.js has enabled the compile cache successfully. The directory used to store the
478+
compile cache will be returned in the <code>directory</code> field in the
479+
returned object.
480+
</td>
481+
</tr>
482+
<tr>
483+
<td><code>ALREADY_ENABLED</code></td>
484+
<td>
485+
The compile cache has already been enabled before, either by a previous call to
486+
<code>module.enableCompileCache()</code>, or by the <code>NODE_COMPILE_CACHE=dir</code>
487+
environment variable. The directory used to store the
488+
compile cache will be returned in the <code>directory</code> field in the
489+
returned object.
490+
</td>
491+
</tr>
492+
<tr>
493+
<td><code>FAILED</code></td>
494+
<td>
495+
Node.js fails to enable the compile cache. This can be caused by the lack of
496+
permission to use the specified directory, or various kinds of file system errors.
497+
The detail of the failure will be returned in the <code>message</code> field in the
498+
returned object.
499+
</td>
500+
</tr>
501+
<tr>
502+
<td><code>DISABLED</code></td>
503+
<td>
504+
Node.js cannot enable the compile cache because the environment variable
505+
<code>NODE_DISABLE_COMPILE_CACHE=1</code> has been set.
506+
</td>
507+
</tr>
508+
</table>
509+
510+
### `module.enableCompileCache([cacheDir])`
511+
512+
<!-- YAML
513+
added: v22.8.0
514+
-->
515+
516+
> Stability: 1.1 - Active Development
517+
518+
* `cacheDir` {string|undefined} Optional path to specify the directory where the compile cache
519+
will be stored/retrieved.
520+
* Returns: {Object}
521+
* `status` {integer} One of the [`module.constants.compileCacheStatus`][]
522+
* `message` {string|undefined} If Node.js cannot enable the compile cache, this contains
523+
the error message. Only set if `status` is `module.constants.compileCacheStatus.FAILED`.
524+
* `directory` {string|undefined} If the compile cache is enabled, this contains the directory
525+
where the compile cache is stored. Only set if `status` is
526+
`module.constants.compileCacheStatus.ENABLED` or
527+
`module.constants.compileCacheStatus.ALREADY_ENABLED`.
528+
529+
Enable [module compile cache][] in the current Node.js instance.
530+
531+
If `cacheDir` is not specified, Node.js will either use the directory specified by the
532+
[`NODE_COMPILE_CACHE=dir`][] environment variable if it's set, or use
533+
`path.join(os.tmpdir(), 'node-compile-cache')` otherwise. For general use cases, it's
534+
recommended to call `module.enableCompileCache()` without specifying the `cacheDir`,
535+
so that the directory can be overridden by the `NODE_COMPILE_CACHE` environment
536+
variable when necessary.
537+
538+
Since compile cache is supposed to be a quiet optimization that is not required for the
539+
application to be functional, this method is designed to not throw any exception when the
540+
compile cache cannot be enabled. Instead, it will return an object containing an error
541+
message in the `message` field to aid debugging.
542+
If compile cache is enabled successfully, the `directory` field in the returned object
543+
contains the path to the directory where the compile cache is stored. The `status`
544+
field in the returned object would be one of the `module.constants.compileCacheStatus`
545+
values to indicate the result of the attempt to enable the [module compile cache][].
546+
547+
This method only affects the current Node.js instance. To enable it in child worker threads,
548+
either call this method in child worker threads too, or set the
549+
`process.env.NODE_COMPILE_CACHE` value to compile cache directory so the behavior can
550+
be inherited into the child workers. The directory can be obtained either from the
551+
`directory` field returned by this method, or with [`module.getCompileCacheDir()`][].
552+
553+
### `module.flushCompileCache()`
554+
555+
<!-- YAML
556+
added:
557+
- v23.0.0
558+
- v22.10.0
559+
-->
560+
561+
> Stability: 1.1 - Active Development
562+
563+
Flush the [module compile cache][] accumulated from modules already loaded
564+
in the current Node.js instance to disk. This returns after all the flushing
565+
file system operations come to an end, no matter they succeed or not. If there
566+
are any errors, this will fail silently, since compile cache misses should not
567+
interfere with the actual operation of the application.
568+
569+
### `module.getCompileCacheDir()`
570+
571+
<!-- YAML
572+
added: v22.8.0
573+
-->
574+
575+
> Stability: 1.1 - Active Development
576+
577+
* Returns: {string|undefined} Path to the [module compile cache][] directory if it is enabled,
578+
or `undefined` otherwise.
579+
411580
<i id="module_customization_hooks"></i>
412581
413582
## Customization Hooks
@@ -1204,21 +1373,6 @@ added:
12041373
`path` is the resolved path for the file for which a corresponding source map
12051374
should be fetched.
12061375
1207-
### `module.flushCompileCache()`
1208-
1209-
<!-- YAML
1210-
added:
1211-
- v22.10.0
1212-
-->
1213-
1214-
> Stability: 1.1 - Active Development
1215-
1216-
Flush the [module compile cache][] accumulated from modules already loaded
1217-
in the current Node.js instance to disk. This returns after all the flushing
1218-
file system operations come to an end, no matter they succeed or not. If there
1219-
are any errors, this will fail silently, since compile cache misses should not
1220-
interfer with the actual operation of the application.
1221-
12221376
### Class: `module.SourceMap`
12231377
12241378
<!-- YAML

0 commit comments

Comments
0 (0)
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.