Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
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>
  • Loading branch information
aduh95 authored and MylesBorins committed Nov 16, 2020
1 parent 18f01dd commit f0b06b6
Show file tree
Hide file tree
Showing 7 changed files with 215 additions and 184 deletions.
1 change: 1 addition & 0 deletions .eslintrc.js
Expand Up @@ -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',
Expand Down
2 changes: 1 addition & 1 deletion doc/api/deprecations.md
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions doc/api/esm.md
Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions doc/api/index.md
Expand Up @@ -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)
Expand Down
194 changes: 194 additions & 0 deletions doc/api/module.md
@@ -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

0 comments on commit f0b06b6

Please sign in to comment.