FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

doc: move module core module doc to separate page · nodejs/node@34430ab · GitHub

/ node Public

Commit 34430ab

Browse files
aduh95
authored and
BethGriggs
committed
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: #34747 Refs: nodejs/modules#539 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: James M Snell <jasnell@gmail.com>
1 parent cdd4540 commit 34430ab

7 files changed

Lines changed: 215 additions & 184 deletions

File tree

‎.eslintrc.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ module.exports = {
4343
{
4444
files: [
4545
'doc/api/esm.md',
46+
'doc/api/module.md',
4647
'doc/api/modules.md',
4748
'test/es-module/test-esm-type-flag.js',
4849
'test/es-module/test-esm-type-flag-alias.js',

‎doc/api/deprecations.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2821,7 +2821,7 @@ The [`crypto.Certificate()` constructor][] is deprecated. Use
28212821
[`http.request()`]: http.html#http_http_request_options_callback
28222822
[`https.get()`]: https.html#https_https_get_options_callback
28232823
[`https.request()`]: https.html#https_https_request_options_callback
2824-
[`module.createRequire()`]: modules.html#modules_module_createrequire_filename
2824+
[`module.createRequire()`]: module.html#module_module_createrequire_filename
28252825
[`os.networkInterfaces()`]: os.html#os_os_networkinterfaces
28262826
[`os.tmpdir()`]: os.html#os_os_tmpdir
28272827
[`process.env`]: process.html#process_process_env

‎doc/api/esm.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1920,8 +1920,8 @@ success!
19201920
[`import()`]: #esm_import_expressions
19211921
[`import.meta.url`]: #esm_import_meta
19221922
[`import`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import
1923-
[`module.createRequire()`]: modules.html#modules_module_createrequire_filename
1924-
[`module.syncBuiltinESMExports()`]: modules.html#modules_module_syncbuiltinesmexports
1923+
[`module.createRequire()`]: module.html#module_module_createrequire_filename
1924+
[`module.syncBuiltinESMExports()`]: module.html#module_module_syncbuiltinesmexports
19251925
[`transformSource` hook]: #esm_transformsource_source_context_defaulttransformsource
19261926
[`ArrayBuffer`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer
19271927
[`SharedArrayBuffer`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer

‎doc/api/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@
3636
* [Inspector](inspector.html)
3737
* [Internationalization](intl.html)
3838
* [Modules](modules.html)
39+
* [Modules: `module` core module](module.html)
3940
* [Net](net.html)
4041
* [OS](os.html)
4142
* [Path](path.html)

‎doc/api/module.md‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
# Modules: `module` core module
2+
3+
<!--introduced_in=v0.3.7-->
4+
5+
## The `Module` object
6+
7+
* {Object}
8+
9+
Provides general utility methods when interacting with instances of
10+
`Module`, the `module` variable often seen in file modules. Accessed
11+
via `require('module')`.
12+
13+
### `module.builtinModules`
14+
<!-- YAML
15+
added:
16+
- v9.3.0
17+
- v8.10.0
18+
- v6.13.0
19+
-->
20+
21+
* {string[]}
22+
23+
A list of the names of all modules provided by Node.js. Can be used to verify
24+
if a module is maintained by a third party or not.
25+
26+
`module` in this context isn't the same object that's provided
27+
by the [module wrapper][]. To access it, require the `Module` module:
28+
29+
```js
30+
const builtin = require('module').builtinModules;
31+
```
32+
33+
### `module.createRequire(filename)`
34+
<!-- YAML
35+
added: v12.2.0
36+
-->
37+
38+
* `filename` {string|URL} Filename to be used to construct the require
39+
function. Must be a file URL object, file URL string, or absolute path
40+
string.
41+
* Returns: {require} Require function
42+
43+
```js
44+
import { createRequire } from 'module';
45+
const require = createRequire(import.meta.url);
46+
47+
// sibling-module.js is a CommonJS module.
48+
const siblingModule = require('./sibling-module');
49+
```
50+
51+
### `module.createRequireFromPath(filename)`
52+
<!-- YAML
53+
added: v10.12.0
54+
deprecated: v12.2.0
55+
-->
56+
57+
> Stability: 0 - Deprecated: Please use [`createRequire()`][] instead.
58+
59+
* `filename` {string} Filename to be used to construct the relative require
60+
function.
61+
* Returns: {require} Require function
62+
63+
```js
64+
const { createRequireFromPath } = require('module');
65+
const requireUtil = createRequireFromPath('../src/utils/');
66+
67+
// Require `../src/utils/some-tool`
68+
requireUtil('./some-tool');
69+
```
70+
71+
### `module.syncBuiltinESMExports()`
72+
<!-- YAML
73+
added: v12.12.0
74+
-->
75+
76+
The `module.syncBuiltinESMExports()` method updates all the live bindings for
77+
builtin ES Modules to match the properties of the CommonJS exports. It does
78+
not add or remove exported names from the ES Modules.
79+
80+
```js
81+
const fs = require('fs');
82+
const { syncBuiltinESMExports } = require('module');
83+
84+
fs.readFile = null;
85+
86+
delete fs.readFileSync;
87+
88+
fs.newAPI = function newAPI() {
89+
// ...
90+
};
91+
92+
syncBuiltinESMExports();
93+
94+
import('fs').then((esmFS) => {
95+
assert.strictEqual(esmFS.readFile, null);
96+
assert.strictEqual('readFileSync' in fs, true);
97+
assert.strictEqual(esmFS.newAPI, undefined);
98+
});
99+
```
100+
101+
## Source map v3 support
102+
<!-- YAML
103+
added:
104+
- v13.7.0
105+
- v12.17.0
106+
-->
107+
108+
> Stability: 1 - Experimental
109+
110+
Helpers for interacting with the source map cache. This cache is
111+
populated when source map parsing is enabled and
112+
[source map include directives][] are found in a modules' footer.
113+
114+
To enable source map parsing, Node.js must be run with the flag
115+
[`--enable-source-maps`][], or with code coverage enabled by setting
116+
[`NODE_V8_COVERAGE=dir`][].
117+
118+
```js
119+
const { findSourceMap, SourceMap } = require('module');
120+
```
121+
122+
### `module.findSourceMap(path[, error])`
123+
<!-- YAML
124+
added:
125+
- v13.7.0
126+
- v12.17.0
127+
-->
128+
129+
* `path` {string}
130+
* `error` {Error}
131+
* Returns: {module.SourceMap}
132+
133+
`path` is the resolved path for the file for which a corresponding source map
134+
should be fetched.
135+
136+
The `error` instance should be passed as the second parameter to `findSourceMap`
137+
in exceptional flows, e.g., when an overridden
138+
[`Error.prepareStackTrace(error, trace)`][] is invoked. Modules are not added to
139+
the module cache until they are successfully loaded, in these cases source maps
140+
will be associated with the `error` instance along with the `path`.
141+
142+
### Class: `module.SourceMap`
143+
<!-- YAML
144+
added:
145+
- v13.7.0
146+
- v12.17.0
147+
-->
148+
149+
#### `new SourceMap(payload)`
150+
151+
* `payload` {Object}
152+
153+
Creates a new `sourceMap` instance.
154+
155+
`payload` is an object with keys matching the [Source map v3 format][]:
156+
157+
* `file`: {string}
158+
* `version`: {number}
159+
* `sources`: {string[]}
160+
* `sourcesContent`: {string[]}
161+
* `names`: {string[]}
162+
* `mappings`: {string}
163+
* `sourceRoot`: {string}
164+
165+
#### `sourceMap.payload`
166+
167+
* Returns: {Object}
168+
169+
Getter for the payload used to construct the [`SourceMap`][] instance.
170+
171+
#### `sourceMap.findEntry(lineNumber, columnNumber)`
172+
173+
* `lineNumber` {number}
174+
* `columnNumber` {number}
175+
* Returns: {Object}
176+
177+
Given a line number and column number in the generated source file, returns
178+
an object representing the position in the original file. The object returned
179+
consists of the following keys:
180+
181+
* generatedLine: {number}
182+
* generatedColumn: {number}
183+
* originalSource: {string}
184+
* originalLine: {number}
185+
* originalColumn: {number}
186+
187+
[`createRequire()`]: #module_module_createrequire_filename
188+
[module wrapper]: modules_cjs.html#modules_cjs_the_module_wrapper
189+
[source map include directives]: https://sourcemaps.info/spec.html#h.lmz475t4mvbx
190+
[`--enable-source-maps`]: cli.html#cli_enable_source_maps
191+
[`NODE_V8_COVERAGE=dir`]: cli.html#cli_node_v8_coverage_dir
192+
[`Error.prepareStackTrace(error, trace)`]: https://v8.dev/docs/stack-trace-api#customizing-stack-traces
193+
[`SourceMap`]: #module_class_module_sourcemap
194+
[Source map v3 format]: https://sourcemaps.info/spec.html#h.mofvlxcwqzej

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL