Skip to content

Commit d48b522

Browse files
legendecasaduh95
legendecas
authored and
aduh95
committed
doc: fix module.md headings
PR-URL: #56131 Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Marco Ippolito <marcoippolito54@gmail.com>
1 parent a75ca13 commit d48b522

File tree

1 file changed

+169
-169
lines changed

1 file changed

+169
-169
lines changed

‎doc/api/module.md‎

Lines changed: 169 additions & 169 deletions
Original file line numberDiff line numberDiff line change
@@ -64,159 +64,6 @@ const require = createRequire(import.meta.url);
6464
const siblingModule = require('./sibling-module');
6565
```
6666
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-
22067
### `module.findPackageJSON(specifier[, base])`
22168
22269
<!-- YAML
@@ -352,7 +199,7 @@ changes:
352199
Register a module that exports [hooks][] that customize Node.js module
353200
resolution and loading behavior. See [Customization hooks][].
354201
355-
## `module.stripTypeScriptTypes(code[, options])`
202+
### `module.stripTypeScriptTypes(code[, options])`
356203
357204
<!-- YAML
358205
added: v23.2.0
@@ -490,6 +337,174 @@ import('node:fs').then((esmFS) => {
490337
});
491338
```
492339
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+
493508
<i id="module_customization_hooks"></i>
494509
495510
## Customization Hooks
@@ -1285,21 +1300,6 @@ added:
12851300
`path` is the resolved path for the file for which a corresponding source map
12861301
should be fetched.
12871302
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-
13031303
### Class: `module.SourceMap`
13041304
13051305
<!-- YAML

0 commit comments

Comments
 (0)