Skip to content

Commit 1452d74

Browse files
committed
doc: fix module.md headings
1 parent 3b6da7c commit 1452d74

File tree

1 file changed

+117
-117
lines changed

1 file changed

+117
-117
lines changed

doc/api/module.md

Lines changed: 117 additions & 117 deletions
Original file line numberDiff line numberDiff line change
@@ -117,106 +117,6 @@ The following constants are returned as the `status` field in the object returne
117117
</tr>
118118
</table>
119119
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-
220120
### `module.findPackageJSON(specifier[, base])`
221121
222122
<!-- YAML
@@ -352,7 +252,7 @@ changes:
352252
Register a module that exports [hooks][] that customize Node.js module
353253
resolution and loading behavior. See [Customization hooks][].
354254
355-
## `module.stripTypeScriptTypes(code[, options])`
255+
### `module.stripTypeScriptTypes(code[, options])`
356256
357257
<!-- YAML
358258
added: v23.2.0
@@ -490,6 +390,122 @@ import('node:fs').then((esmFS) => {
490390
});
491391
```
492392
393+
## Module compile cache
394+
395+
<!-- YAML
396+
added: v22.1.0
397+
changes:
398+
- version: v22.8.0
399+
pr-url: https://github.com/nodejs/node/pull/54501
400+
description: add initial JavaScript APIs for runtime access.
401+
-->
402+
403+
The module compile cache can be enabled either using the [`module.enableCompileCache()`][]
404+
method or the [`NODE_COMPILE_CACHE=dir`][] environment variable. After it is enabled,
405+
whenever Node.js compiles a CommonJS or a ECMAScript Module, it will use on-disk
406+
[V8 code cache][] persisted in the specified directory to speed up the compilation.
407+
This may slow down the first load of a module graph, but subsequent loads of the same module
408+
graph may get a significant speedup if the contents of the modules do not change.
409+
410+
To clean up the generated compile cache on disk, simply remove the cache directory. The cache
411+
directory will be recreated the next time the same directory is used for for compile cache
412+
storage. To avoid filling up the disk with stale cache, it is recommended to use a directory
413+
under the [`os.tmpdir()`][]. If the compile cache is enabled by a call to
414+
[`module.enableCompileCache()`][] without specifying the directory, Node.js will use
415+
the [`NODE_COMPILE_CACHE=dir`][] environment variable if it's set, or defaults
416+
to `path.join(os.tmpdir(), 'node-compile-cache')` otherwise. To locate the compile cache
417+
directory used by a running Node.js instance, use [`module.getCompileCacheDir()`][].
418+
419+
Currently when using the compile cache with [V8 JavaScript code coverage][], the
420+
coverage being collected by V8 may be less precise in functions that are
421+
deserialized from the code cache. It's recommended to turn this off when
422+
running tests to generate precise coverage.
423+
424+
The enabled module compile cache can be disabled by the [`NODE_DISABLE_COMPILE_CACHE=1`][]
425+
environment variable. This can be useful when the compile cache leads to unexpected or
426+
undesired behaviors (e.g. less precise test coverage).
427+
428+
Compilation cache generated by one version of Node.js can not be reused by a different
429+
version of Node.js. Cache generated by different versions of Node.js will be stored
430+
separately if the same base directory is used to persist the cache, so they can co-exist.
431+
432+
At the moment, when the compile cache is enabled and a module is loaded afresh, the
433+
code cache is generated from the compiled code immediately, but will only be written
434+
to disk when the Node.js instance is about to exit. This is subject to change. The
435+
[`module.flushCompileCache()`][] method can be used to ensure the accumulated code cache
436+
is flushed to disk in case the application wants to spawn other Node.js instances
437+
and let them share the cache long before the parent exits.
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+
- v22.10.0
488+
-->
489+
490+
> Stability: 1.1 - Active Development
491+
492+
Flush the [module compile cache][] accumulated from modules already loaded
493+
in the current Node.js instance to disk. This returns after all the flushing
494+
file system operations come to an end, no matter they succeed or not. If there
495+
are any errors, this will fail silently, since compile cache misses should not
496+
interfere with the actual operation of the application.
497+
498+
### `module.getCompileCacheDir()`
499+
500+
<!-- YAML
501+
added: v22.8.0
502+
-->
503+
504+
> Stability: 1.1 - Active Development
505+
506+
* Returns: {string|undefined} Path to the [module compile cache][] directory if it is enabled,
507+
or `undefined` otherwise.
508+
493509
<i id="module_customization_hooks"></i>
494510
495511
## Customization Hooks
@@ -1285,22 +1301,6 @@ added:
12851301
`path` is the resolved path for the file for which a corresponding source map
12861302
should be fetched.
12871303
1288-
### `module.flushCompileCache()`
1289-
1290-
<!-- YAML
1291-
added:
1292-
- v23.0.0
1293-
- v22.10.0
1294-
-->
1295-
1296-
> Stability: 1.1 - Active Development
1297-
1298-
Flush the [module compile cache][] accumulated from modules already loaded
1299-
in the current Node.js instance to disk. This returns after all the flushing
1300-
file system operations come to an end, no matter they succeed or not. If there
1301-
are any errors, this will fail silently, since compile cache misses should not
1302-
interfere with the actual operation of the application.
1303-
13041304
### Class: `module.SourceMap`
13051305
13061306
<!-- YAML

0 commit comments

Comments
 (0)