mirror of
https://github.com/zebrajr/node.git
synced 2025-12-06 12:20:27 +01:00
doc: move module core module doc to separate page
The `module` core module is available for both CJS and ESM users, it deserves its own page. PR-URL: https://github.com/nodejs/node/pull/34747 Refs: https://github.com/nodejs/modules/issues/539 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: James M Snell <jasnell@gmail.com>
This commit is contained in:
Antoine du HAMEL
Myles Borins
parent
18f01ddcb5
commit
f0b06b64ff
|
|
@ -43,6 +43,7 @@ module.exports = {
|
|||
{
|
||||
files: [
|
||||
'doc/api/esm.md',
|
||||
'doc/api/module.md',
|
||||
'doc/api/modules.md',
|
||||
'doc/api/packages.md',
|
||||
'test/es-module/test-esm-type-flag.js',
|
||||
|
|
|
|||
|
|
@ -2644,7 +2644,7 @@ const moduleParents = Object.values(require.cache)
|
|||
[`http.request()`]: http.html#http_http_request_options_callback
|
||||
[`https.get()`]: https.html#https_https_get_options_callback
|
||||
[`https.request()`]: https.html#https_https_request_options_callback
|
||||
[`module.createRequire()`]: modules.html#modules_module_createrequire_filename
|
||||
[`module.createRequire()`]: module.html#module_module_createrequire_filename
|
||||
[`os.networkInterfaces()`]: os.html#os_os_networkinterfaces
|
||||
[`os.tmpdir()`]: os.html#os_os_tmpdir
|
||||
[`process.env`]: process.html#process_process_env
|
||||
|
|
|
|||
|
|
@ -1278,8 +1278,8 @@ success!
|
|||
[`import()`]: #esm_import_expressions
|
||||
[`import.meta.url`]: #esm_import_meta
|
||||
[`import`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import
|
||||
[`module.createRequire()`]: modules.html#modules_module_createrequire_filename
|
||||
[`module.syncBuiltinESMExports()`]: modules.html#modules_module_syncbuiltinesmexports
|
||||
[`module.createRequire()`]: module.html#module_module_createrequire_filename
|
||||
[`module.syncBuiltinESMExports()`]: module.html#module_module_syncbuiltinesmexports
|
||||
[`transformSource` hook]: #esm_transformsource_source_context_defaulttransformsource
|
||||
[`ArrayBuffer`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer
|
||||
[`SharedArrayBuffer`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer
|
||||
|
|
|
|||
|
|
@ -36,6 +36,7 @@
|
|||
* [Internationalization](intl.html)
|
||||
* [Modules: CommonJS modules](modules.html)
|
||||
* [Modules: ECMAScript modules](esm.html)
|
||||
* [Modules: `module` API](module.html)
|
||||
* [Modules: Packages](packages.html)
|
||||
* [Net](net.html)
|
||||
* [OS](os.html)
|
||||
|
|
|
|||
194
doc/api/module.md
Normal file
194
doc/api/module.md
Normal file
|
|
@ -0,0 +1,194 @@
|
|||
# Modules: `module` API
|
||||
|
||||
<!--introduced_in=v0.3.7-->
|
||||
|
||||
## The `Module` object
|
||||
|
||||
* {Object}
|
||||
|
||||
Provides general utility methods when interacting with instances of
|
||||
`Module`, the `module` variable often seen in file modules. Accessed
|
||||
via `require('module')`.
|
||||
|
||||
### `module.builtinModules`
|
||||
<!-- YAML
|
||||
added:
|
||||
- v9.3.0
|
||||
- v8.10.0
|
||||
- v6.13.0
|
||||
-->
|
||||
|
||||
* {string[]}
|
||||
|
||||
A list of the names of all modules provided by Node.js. Can be used to verify
|
||||
if a module is maintained by a third party or not.
|
||||
|
||||
`module` in this context isn't the same object that's provided
|
||||
by the [module wrapper][]. To access it, require the `Module` module:
|
||||
|
||||
```js
|
||||
const builtin = require('module').builtinModules;
|
||||
```
|
||||
|
||||
### `module.createRequire(filename)`
|
||||
<!-- YAML
|
||||
added: v12.2.0
|
||||
-->
|
||||
|
||||
* `filename` {string|URL} Filename to be used to construct the require
|
||||
function. Must be a file URL object, file URL string, or absolute path
|
||||
string.
|
||||
* Returns: {require} Require function
|
||||
|
||||
```js
|
||||
import { createRequire } from 'module';
|
||||
const require = createRequire(import.meta.url);
|
||||
|
||||
// sibling-module.js is a CommonJS module.
|
||||
const siblingModule = require('./sibling-module');
|
||||
```
|
||||
|
||||
### `module.createRequireFromPath(filename)`
|
||||
<!-- YAML
|
||||
added: v10.12.0
|
||||
deprecated: v12.2.0
|
||||
-->
|
||||
|
||||
> Stability: 0 - Deprecated: Please use [`createRequire()`][] instead.
|
||||
|
||||
* `filename` {string} Filename to be used to construct the relative require
|
||||
function.
|
||||
* Returns: {require} Require function
|
||||
|
||||
```js
|
||||
const { createRequireFromPath } = require('module');
|
||||
const requireUtil = createRequireFromPath('../src/utils/');
|
||||
|
||||
// Require `../src/utils/some-tool`
|
||||
requireUtil('./some-tool');
|
||||
```
|
||||
|
||||
### `module.syncBuiltinESMExports()`
|
||||
<!-- YAML
|
||||
added: v12.12.0
|
||||
-->
|
||||
|
||||
The `module.syncBuiltinESMExports()` method updates all the live bindings for
|
||||
builtin ES Modules to match the properties of the CommonJS exports. It does
|
||||
not add or remove exported names from the ES Modules.
|
||||
|
||||
```js
|
||||
const fs = require('fs');
|
||||
const { syncBuiltinESMExports } = require('module');
|
||||
|
||||
fs.readFile = null;
|
||||
|
||||
delete fs.readFileSync;
|
||||
|
||||
fs.newAPI = function newAPI() {
|
||||
// ...
|
||||
};
|
||||
|
||||
syncBuiltinESMExports();
|
||||
|
||||
import('fs').then((esmFS) => {
|
||||
assert.strictEqual(esmFS.readFile, null);
|
||||
assert.strictEqual('readFileSync' in fs, true);
|
||||
assert.strictEqual(esmFS.newAPI, undefined);
|
||||
});
|
||||
```
|
||||
|
||||
## Source map v3 support
|
||||
<!-- YAML
|
||||
added:
|
||||
- v13.7.0
|
||||
- v12.17.0
|
||||
-->
|
||||
|
||||
> Stability: 1 - Experimental
|
||||
|
||||
Helpers for interacting with the source map cache. This cache is
|
||||
populated when source map parsing is enabled and
|
||||
[source map include directives][] are found in a modules' footer.
|
||||
|
||||
To enable source map parsing, Node.js must be run with the flag
|
||||
[`--enable-source-maps`][], or with code coverage enabled by setting
|
||||
[`NODE_V8_COVERAGE=dir`][].
|
||||
|
||||
```js
|
||||
const { findSourceMap, SourceMap } = require('module');
|
||||
```
|
||||
|
||||
### `module.findSourceMap(path[, error])`
|
||||
<!-- YAML
|
||||
added:
|
||||
- v13.7.0
|
||||
- v12.17.0
|
||||
-->
|
||||
|
||||
* `path` {string}
|
||||
* `error` {Error}
|
||||
* Returns: {module.SourceMap}
|
||||
|
||||
`path` is the resolved path for the file for which a corresponding source map
|
||||
should be fetched.
|
||||
|
||||
The `error` instance should be passed as the second parameter to `findSourceMap`
|
||||
in exceptional flows, e.g., when an overridden
|
||||
[`Error.prepareStackTrace(error, trace)`][] is invoked. Modules are not added to
|
||||
the module cache until they are successfully loaded, in these cases source maps
|
||||
will be associated with the `error` instance along with the `path`.
|
||||
|
||||
### Class: `module.SourceMap`
|
||||
<!-- YAML
|
||||
added:
|
||||
- v13.7.0
|
||||
- v12.17.0
|
||||
-->
|
||||
|
||||
#### `new SourceMap(payload)`
|
||||
|
||||
* `payload` {Object}
|
||||
|
||||
Creates a new `sourceMap` instance.
|
||||
|
||||
`payload` is an object with keys matching the [Source map v3 format][]:
|
||||
|
||||
* `file`: {string}
|
||||
* `version`: {number}
|
||||
* `sources`: {string[]}
|
||||
* `sourcesContent`: {string[]}
|
||||
* `names`: {string[]}
|
||||
* `mappings`: {string}
|
||||
* `sourceRoot`: {string}
|
||||
|
||||
#### `sourceMap.payload`
|
||||
|
||||
* Returns: {Object}
|
||||
|
||||
Getter for the payload used to construct the [`SourceMap`][] instance.
|
||||
|
||||
#### `sourceMap.findEntry(lineNumber, columnNumber)`
|
||||
|
||||
* `lineNumber` {number}
|
||||
* `columnNumber` {number}
|
||||
* Returns: {Object}
|
||||
|
||||
Given a line number and column number in the generated source file, returns
|
||||
an object representing the position in the original file. The object returned
|
||||
consists of the following keys:
|
||||
|
||||
* generatedLine: {number}
|
||||
* generatedColumn: {number}
|
||||
* originalSource: {string}
|
||||
* originalLine: {number}
|
||||
* originalColumn: {number}
|
||||
|
||||
[`createRequire()`]: #module_module_createrequire_filename
|
||||
[module wrapper]: modules_cjs.html#modules_cjs_the_module_wrapper
|
||||
[source map include directives]: https://sourcemaps.info/spec.html#h.lmz475t4mvbx
|
||||
[`--enable-source-maps`]: cli.html#cli_enable_source_maps
|
||||
[`NODE_V8_COVERAGE=dir`]: cli.html#cli_node_v8_coverage_dir
|
||||
[`Error.prepareStackTrace(error, trace)`]: https://v8.dev/docs/stack-trace-api#customizing-stack-traces
|
||||
[`SourceMap`]: #module_class_module_sourcemap
|
||||
[Source map v3 format]: https://sourcemaps.info/spec.html#h.mofvlxcwqzej
|
||||
|
|
@ -953,189 +953,31 @@ in order to be used.
|
|||
|
||||
## The `Module` object
|
||||
|
||||
<!-- YAML
|
||||
added: v0.3.7
|
||||
-->
|
||||
This section was moved to
|
||||
[Modules: `module` core module](modules_module.html#modules_module_the_module_object).
|
||||
|
||||
* {Object}
|
||||
|
||||
Provides general utility methods when interacting with instances of
|
||||
`Module`, the `module` variable often seen in file modules. Accessed
|
||||
via `require('module')`.
|
||||
|
||||
### `module.builtinModules`
|
||||
<!-- YAML
|
||||
added:
|
||||
- v9.3.0
|
||||
- v8.10.0
|
||||
- v6.13.0
|
||||
-->
|
||||
|
||||
* {string[]}
|
||||
|
||||
A list of the names of all modules provided by Node.js. Can be used to verify
|
||||
if a module is maintained by a third party or not.
|
||||
|
||||
`module` in this context isn't the same object that's provided
|
||||
by the [module wrapper][]. To access it, require the `Module` module:
|
||||
|
||||
```js
|
||||
const builtin = require('module').builtinModules;
|
||||
```
|
||||
|
||||
### `module.createRequire(filename)`
|
||||
<!-- YAML
|
||||
added: v12.2.0
|
||||
-->
|
||||
|
||||
* `filename` {string|URL} Filename to be used to construct the require
|
||||
function. Must be a file URL object, file URL string, or absolute path
|
||||
string.
|
||||
* Returns: {require} Require function
|
||||
|
||||
```js
|
||||
import { createRequire } from 'module';
|
||||
const require = createRequire(import.meta.url);
|
||||
|
||||
// sibling-module.js is a CommonJS module.
|
||||
const siblingModule = require('./sibling-module');
|
||||
```
|
||||
|
||||
### `module.createRequireFromPath(filename)`
|
||||
<!-- YAML
|
||||
added: v10.12.0
|
||||
deprecated: v12.2.0
|
||||
-->
|
||||
|
||||
> Stability: 0 - Deprecated: Please use [`createRequire()`][] instead.
|
||||
|
||||
* `filename` {string} Filename to be used to construct the relative require
|
||||
function.
|
||||
* Returns: {require} Require function
|
||||
|
||||
```js
|
||||
const { createRequireFromPath } = require('module');
|
||||
const requireUtil = createRequireFromPath('../src/utils/');
|
||||
|
||||
// Require `../src/utils/some-tool`
|
||||
requireUtil('./some-tool');
|
||||
```
|
||||
|
||||
### `module.syncBuiltinESMExports()`
|
||||
<!-- YAML
|
||||
added: v12.12.0
|
||||
-->
|
||||
|
||||
The `module.syncBuiltinESMExports()` method updates all the live bindings for
|
||||
builtin ES Modules to match the properties of the CommonJS exports. It does
|
||||
not add or remove exported names from the ES Modules.
|
||||
|
||||
```js
|
||||
const fs = require('fs');
|
||||
const { syncBuiltinESMExports } = require('module');
|
||||
|
||||
fs.readFile = null;
|
||||
|
||||
delete fs.readFileSync;
|
||||
|
||||
fs.newAPI = function newAPI() {
|
||||
// ...
|
||||
};
|
||||
|
||||
syncBuiltinESMExports();
|
||||
|
||||
import('fs').then((esmFS) => {
|
||||
assert.strictEqual(esmFS.readFile, null);
|
||||
assert.strictEqual('readFileSync' in fs, true);
|
||||
assert.strictEqual(esmFS.newAPI, undefined);
|
||||
});
|
||||
```
|
||||
<!-- Anchors to make sure old links find a target -->
|
||||
* <a id="modules_module_builtinmodules" href="module.html#module_module_builtinmodules">`module.builtinModules`</a>
|
||||
* <a id="modules_module_createrequire_filename" href="module.html#module_module_createrequire_filename">`module.createRequire(filename)`</a>
|
||||
* <a id="modules_module_createrequirefrompath_filename" href="module.html#module_module_createrequirefrompath_filename">`module.createRequireFromPath(filename)`</a>
|
||||
* <a id="modules_module_syncbuiltinesmexports" href="module.html#module_module_syncbuiltinesmexports">`module.syncBuiltinESMExports()`</a>
|
||||
|
||||
## Source map v3 support
|
||||
<!-- YAML
|
||||
added: v12.17.0
|
||||
-->
|
||||
|
||||
> Stability: 1 - Experimental
|
||||
This section was moved to
|
||||
[Modules: `module` core module](modules_module.html#modules_module_source_map_v3_support).
|
||||
|
||||
Helpers for interacting with the source map cache. This cache is
|
||||
populated when source map parsing is enabled and
|
||||
[source map include directives][] are found in a modules' footer.
|
||||
|
||||
To enable source map parsing, Node.js must be run with the flag
|
||||
[`--enable-source-maps`][], or with code coverage enabled by setting
|
||||
[`NODE_V8_COVERAGE=dir`][].
|
||||
|
||||
```js
|
||||
const { findSourceMap, SourceMap } = require('module');
|
||||
```
|
||||
|
||||
### `module.findSourceMap(path[, error])`
|
||||
<!-- YAML
|
||||
added: v12.17.0
|
||||
-->
|
||||
|
||||
* `path` {string}
|
||||
* `error` {Error}
|
||||
* Returns: {module.SourceMap}
|
||||
|
||||
`path` is the resolved path for the file for which a corresponding source map
|
||||
should be fetched.
|
||||
|
||||
The `error` instance should be passed as the second parameter to `findSourceMap`
|
||||
in exceptional flows, e.g., when an overridden
|
||||
[`Error.prepareStackTrace(error, trace)`][] is invoked. Modules are not added to
|
||||
the module cache until they are successfully loaded, in these cases source maps
|
||||
will be associated with the `error` instance along with the `path`.
|
||||
|
||||
### Class: `module.SourceMap`
|
||||
<!-- YAML
|
||||
added: v12.17.0
|
||||
-->
|
||||
|
||||
#### `new SourceMap(payload)`
|
||||
|
||||
* `payload` {Object}
|
||||
|
||||
Creates a new `sourceMap` instance.
|
||||
|
||||
`payload` is an object with keys matching the [Source map v3 format][]:
|
||||
|
||||
* `file`: {string}
|
||||
* `version`: {number}
|
||||
* `sources`: {string[]}
|
||||
* `sourcesContent`: {string[]}
|
||||
* `names`: {string[]}
|
||||
* `mappings`: {string}
|
||||
* `sourceRoot`: {string}
|
||||
|
||||
#### `sourceMap.payload`
|
||||
|
||||
* Returns: {Object}
|
||||
|
||||
Getter for the payload used to construct the [`SourceMap`][] instance.
|
||||
|
||||
#### `sourceMap.findEntry(lineNumber, columnNumber)`
|
||||
|
||||
* `lineNumber` {number}
|
||||
* `columnNumber` {number}
|
||||
* Returns: {Object}
|
||||
|
||||
Given a line number and column number in the generated source file, returns
|
||||
an object representing the position in the original file. The object returned
|
||||
consists of the following keys:
|
||||
|
||||
* generatedLine: {number}
|
||||
* generatedColumn: {number}
|
||||
* originalSource: {string}
|
||||
* originalLine: {number}
|
||||
* originalColumn: {number}
|
||||
<!-- Anchors to make sure old links find a target -->
|
||||
* <a id="modules_module_findsourcemap_path_error" href="module.html#module_module_findsourcemap_path_error">`module.findSourceMap(path[, error])`</a>
|
||||
* <a id="modules_class_module_sourcemap" href="module.html#module_class_module_sourcemap">Class: `module.SourceMap`</a>
|
||||
* <a id="modules_new_sourcemap_payload" href="module.html#module_new_sourcemap_payload">`new SourceMap(payload)`</a>
|
||||
* <a id="modules_sourcemap_payload" href="module.html#module_sourcemap_payload">`sourceMap.payload`</a>
|
||||
* <a id="modules_sourcemap_findentry_linenumber_columnnumber" href="module.html#module_sourcemap_findentry_linenumber_columnnumber">`sourceMap.findEntry(lineNumber, columnNumber)`</a>
|
||||
|
||||
[GLOBAL_FOLDERS]: #modules_loading_from_the_global_folders
|
||||
[`Error`]: errors.html#errors_class_error
|
||||
[`__dirname`]: #modules_dirname
|
||||
[`__filename`]: #modules_filename
|
||||
[`createRequire()`]: #modules_module_createrequire_filename
|
||||
[`module` object]: #modules_the_module_object
|
||||
[`module.id`]: #modules_module_id
|
||||
[`module.children`]: #modules_module_children
|
||||
|
|
@ -1144,14 +986,7 @@ consists of the following keys:
|
|||
[an error]: errors.html#errors_err_require_esm
|
||||
[exports shortcut]: #modules_exports_shortcut
|
||||
[module resolution]: #modules_all_together
|
||||
[module wrapper]: #modules_the_module_wrapper
|
||||
[native addons]: addons.html
|
||||
[`require.main`]: #modules_require_main
|
||||
[source map include directives]: https://sourcemaps.info/spec.html#h.lmz475t4mvbx
|
||||
[`--enable-source-maps`]: cli.html#cli_enable_source_maps
|
||||
[`NODE_V8_COVERAGE=dir`]: cli.html#cli_node_v8_coverage_dir
|
||||
[`Error.prepareStackTrace(error, trace)`]: https://v8.dev/docs/stack-trace-api#customizing-stack-traces
|
||||
[`SourceMap`]: modules.html#modules_class_module_sourcemap
|
||||
[Source map v3 format]: https://sourcemaps.info/spec.html#h.mofvlxcwqzej
|
||||
[`package.json`]: packages.html#packages_node_js_package_json_field_definitions
|
||||
[`"main"`]: packages.html#packages_main
|
||||
|
|
|
|||
|
|
@ -109,7 +109,7 @@ const customTypesMap = {
|
|||
'module': 'modules.html#modules_the_module_object',
|
||||
|
||||
'module.SourceMap':
|
||||
'modules.html#modules_class_module_sourcemap',
|
||||
'modules_module.html#modules_module_class_module_sourcemap',
|
||||
|
||||
'require': 'modules.html#modules_require_id',
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user