From 325fab05165257ef51469d5a06f55165d02948f7 Mon Sep 17 00:00:00 2001 From: Antoine du HAMEL Date: Fri, 7 Aug 2020 12:16:08 +0200 Subject: [PATCH 1/4] 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. --- .eslintrc.js | 1 + doc/api/deprecations.md | 2 +- doc/api/esm.md | 4 +- doc/api/index.md | 1 + doc/api/modules.md | 194 -------------------------------------- doc/api/modules_module.md | 194 ++++++++++++++++++++++++++++++++++++++ tools/doc/type-parser.js | 2 +- 7 files changed, 200 insertions(+), 198 deletions(-) create mode 100644 doc/api/modules_module.md diff --git a/.eslintrc.js b/.eslintrc.js index 8542d2e77e0ea6..30d82cd1ffbff8 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -44,6 +44,7 @@ module.exports = { files: [ 'doc/api/esm.md', 'doc/api/modules.md', + 'doc/api/modules_module.md', 'test/es-module/test-esm-type-flag.js', 'test/es-module/test-esm-type-flag-alias.js', '*.mjs', diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index 165b51e6f476f2..0a5eb5d3d3f66e 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -2828,7 +2828,7 @@ Type: Documentation-only [`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()`]: modules_module.html#modules_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 diff --git a/doc/api/esm.md b/doc/api/esm.md index adbb55f0d82f0d..6fa5da95440e21 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -1949,8 +1949,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()`]: modules_module.html#modules_module_module_createrequire_filename +[`module.syncBuiltinESMExports()`]: modules_module.html#modules_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 diff --git a/doc/api/index.md b/doc/api/index.md index 3f28eb7b0db414..0125734ceb6209 100644 --- a/doc/api/index.md +++ b/doc/api/index.md @@ -36,6 +36,7 @@ * [Inspector](inspector.html) * [Internationalization](intl.html) * [Modules](modules.html) +* [Modules: `module` core module](modules_module.html) * [Net](net.html) * [OS](os.html) * [Path](path.html) diff --git a/doc/api/modules.md b/doc/api/modules.md index 7dda283112bdd8..cee15b6fa57f33 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -951,197 +951,10 @@ Since `require()` returns the `module.exports`, and the `module` is typically *only* available within a specific module's code, it must be explicitly exported in order to be used. -## 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` - - -* {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)` - - -* `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)` - - -> 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()` - - -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 - - -> 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])` - - -* `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` - - -#### `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} - [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 @@ -1150,12 +963,5 @@ 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 diff --git a/doc/api/modules_module.md b/doc/api/modules_module.md new file mode 100644 index 00000000000000..31ee00d13517a0 --- /dev/null +++ b/doc/api/modules_module.md @@ -0,0 +1,194 @@ +# Modules: `module` core 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` + + +* {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)` + + +* `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)` + + +> 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()` + + +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 + + +> 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])` + + +* `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` + + +#### `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()`]: #modules_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`]: #modules_module_class_module_sourcemap +[Source map v3 format]: https://sourcemaps.info/spec.html#h.mofvlxcwqzej diff --git a/tools/doc/type-parser.js b/tools/doc/type-parser.js index 6441b5eef70fda..f20adb91ebcfba 100644 --- a/tools/doc/type-parser.js +++ b/tools/doc/type-parser.js @@ -117,7 +117,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', From 15c9faebe4583fa425f4be4dff8b88b495c57ff5 Mon Sep 17 00:00:00 2001 From: Antoine du HAMEL Date: Wed, 12 Aug 2020 19:22:55 +0200 Subject: [PATCH 2/4] Add redirection links --- doc/api/modules.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/doc/api/modules.md b/doc/api/modules.md index cee15b6fa57f33..bcb0b4e1eda2ca 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -951,6 +951,29 @@ Since `require()` returns the `module.exports`, and the `module` is typically *only* available within a specific module's code, it must be explicitly exported in order to be used. +## The `Module` object + + + + + + + +This section was moved to +[Modules: `module` core module](modules_module.html#modules_module_the_module_object). + +## Source map v3 support + + + + + + + + +This section was moved to +[Modules: `module` core module](modules_module.html#modules_module_source_map_v3_support). + [GLOBAL_FOLDERS]: #modules_loading_from_the_global_folders [`Error`]: errors.html#errors_class_error [`__dirname`]: #modules_dirname From afc26d4c312863eef56557717a31e7a9d53ca5af Mon Sep 17 00:00:00 2001 From: Antoine du HAMEL Date: Thu, 13 Aug 2020 16:29:12 +0200 Subject: [PATCH 3/4] Rename to `module.md` --- .eslintrc.js | 2 +- doc/api/deprecations.md | 2 +- doc/api/esm.md | 4 ++-- doc/api/index.md | 2 +- doc/api/{modules_module.md => module.md} | 4 ++-- 5 files changed, 7 insertions(+), 7 deletions(-) rename doc/api/{modules_module.md => module.md} (97%) diff --git a/.eslintrc.js b/.eslintrc.js index 30d82cd1ffbff8..c13291adaa27e6 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -43,8 +43,8 @@ module.exports = { { files: [ 'doc/api/esm.md', + 'doc/api/module.md', 'doc/api/modules.md', - 'doc/api/modules_module.md', 'test/es-module/test-esm-type-flag.js', 'test/es-module/test-esm-type-flag-alias.js', '*.mjs', diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index 0a5eb5d3d3f66e..e1b4d07e1e8017 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -2828,7 +2828,7 @@ Type: Documentation-only [`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_module.html#modules_module_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 diff --git a/doc/api/esm.md b/doc/api/esm.md index 6fa5da95440e21..9fbcf904fd148d 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -1949,8 +1949,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_module.html#modules_module_module_createrequire_filename -[`module.syncBuiltinESMExports()`]: modules_module.html#modules_module_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 diff --git a/doc/api/index.md b/doc/api/index.md index 0125734ceb6209..304685d77b96f1 100644 --- a/doc/api/index.md +++ b/doc/api/index.md @@ -36,7 +36,7 @@ * [Inspector](inspector.html) * [Internationalization](intl.html) * [Modules](modules.html) -* [Modules: `module` core module](modules_module.html) +* [Modules: `module` core module](module.html) * [Net](net.html) * [OS](os.html) * [Path](path.html) diff --git a/doc/api/modules_module.md b/doc/api/module.md similarity index 97% rename from doc/api/modules_module.md rename to doc/api/module.md index 31ee00d13517a0..98bc8e82f95247 100644 --- a/doc/api/modules_module.md +++ b/doc/api/module.md @@ -184,11 +184,11 @@ consists of the following keys: * originalLine: {number} * originalColumn: {number} -[`createRequire()`]: #modules_module_module_createrequire_filename +[`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`]: #modules_module_class_module_sourcemap +[`SourceMap`]: #module_class_module_sourcemap [Source map v3 format]: https://sourcemaps.info/spec.html#h.mofvlxcwqzej From b051803585de94a2d92ceee72f58bed1eb790ca8 Mon Sep 17 00:00:00 2001 From: Antoine du HAMEL Date: Thu, 13 Aug 2020 16:38:21 +0200 Subject: [PATCH 4/4] Link subsections to the new page --- doc/api/modules.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/doc/api/modules.md b/doc/api/modules.md index bcb0b4e1eda2ca..894bbe3fd87fe8 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -953,27 +953,27 @@ in order to be used. ## The `Module` object - - - - - - This section was moved to [Modules: `module` core module](modules_module.html#modules_module_the_module_object). -## Source map v3 support - - - - - - +* `module.builtinModules` +* `module.createRequire(filename)` +* `module.createRequireFromPath(filename)` +* `module.syncBuiltinESMExports()` + +## Source map v3 support This section was moved to [Modules: `module` core module](modules_module.html#modules_module_source_map_v3_support). + +* `module.findSourceMap(path[, error])` +* Class: `module.SourceMap` + * `new SourceMap(payload)` + * `sourceMap.payload` + * `sourceMap.findEntry(lineNumber, columnNumber)` + [GLOBAL_FOLDERS]: #modules_loading_from_the_global_folders [`Error`]: errors.html#errors_class_error [`__dirname`]: #modules_dirname