From 818cca5625b16fc77ff9469856fc2e5cb66af471 Mon Sep 17 00:00:00 2001 From: Shubherthi Mitra <143800527+shubherthi-mitra@users.noreply.github.com> Date: Thu, 7 Dec 2023 23:56:04 +0530 Subject: [PATCH 1/5] Update packages.md added --experimental-detect-module flag in the docs. --- doc/api/packages.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/doc/api/packages.md b/doc/api/packages.md index 9287ff71c404c9..c03265c2ab62b2 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -231,6 +231,33 @@ For completeness there is also `--input-type=commonjs`, for explicitly running string input as CommonJS. This is the default behavior if `--input-type` is unspecified. +### `--experimental-detect-module` flag + + + +> Stability: 1.0 - Early development + +Node.js will inspect the source code of ambiguous input to determine whether it +contains ES module syntax; if such syntax is detected, the input will be treated +as an ES module. + +Ambiguous input is defined as: + +* Files with a `.js` extension or no extension; and either no controlling + `package.json` file or one that lacks a `type` field; and + `--experimental-default-type` is not specified. +* String input (`--eval` or STDIN) when neither `--input-type` nor + `--experimental-default-type` are specified. + +ES module syntax is defined as syntax that would throw when evaluated as +CommonJS. This includes `import` and `export` statements and `import.meta` +references. It does _not_ include `import()` expressions, which are valid in +CommonJS. + ## Determining package manager > Stability: 1 - Experimental From 92aad946ab0134bae285ba8edbad93229f6ae93a Mon Sep 17 00:00:00 2001 From: Shubherthi Mitra <143800527+shubherthi-mitra@users.noreply.github.com> Date: Fri, 8 Dec 2023 19:57:14 +0530 Subject: [PATCH 2/5] Updated packages.md Mentioned --experimental-detect-module flag and added its reference to cli.md --- doc/api/packages.md | 39 +++++++-------------------------------- 1 file changed, 7 insertions(+), 32 deletions(-) diff --git a/doc/api/packages.md b/doc/api/packages.md index c03265c2ab62b2..9b775f40f1dedc 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -71,11 +71,13 @@ expressions: * Code that contains syntax that only parses successfully as [ES modules][], such as `import` or `export` statements or `import.meta`, when the code has no - explicit marker of how it should be interpreted. Explicit markers are `.mjs` - or `.cjs` extensions, `package.json` `"type"` fields with either `"module"` or - `"commonjs"` values, or `--input-type` or `--experimental-default-type` flags. - Dynamic `import()` expressions are supported in either CommonJS or ES modules - and would not cause a file to be treated as an ES module. + explicit marker of how it should be interpreted. To use this feature + [--experimental-detect-module](https://nodejs.org/docs/latest/api/cli.html) + flag is to be used. Explicit markers are `.mjs` or `.cjs` extensions, + `package.json` `"type"` fields with either `"module"` or `"commonjs"` values, + or `--input-type` or `--experimental-default-type` flags. Dynamic `import()` + expressions are supported in either CommonJS or ES modules and would not + cause a file to be treated as an ES module. Node.js will treat the following as [CommonJS][] when passed to `node` as the initial input, or when referenced by `import` statements or `import()` @@ -231,33 +233,6 @@ For completeness there is also `--input-type=commonjs`, for explicitly running string input as CommonJS. This is the default behavior if `--input-type` is unspecified. -### `--experimental-detect-module` flag - - - -> Stability: 1.0 - Early development - -Node.js will inspect the source code of ambiguous input to determine whether it -contains ES module syntax; if such syntax is detected, the input will be treated -as an ES module. - -Ambiguous input is defined as: - -* Files with a `.js` extension or no extension; and either no controlling - `package.json` file or one that lacks a `type` field; and - `--experimental-default-type` is not specified. -* String input (`--eval` or STDIN) when neither `--input-type` nor - `--experimental-default-type` are specified. - -ES module syntax is defined as syntax that would throw when evaluated as -CommonJS. This includes `import` and `export` statements and `import.meta` -references. It does _not_ include `import()` expressions, which are valid in -CommonJS. - ## Determining package manager > Stability: 1 - Experimental From df062e5821af5a5d69b8b2d14359334fc8f1dbb2 Mon Sep 17 00:00:00 2001 From: Shubherthi Mitra <143800527+shubherthi-mitra@users.noreply.github.com> Date: Fri, 8 Dec 2023 21:25:45 +0530 Subject: [PATCH 3/5] Updated packages.md (more simplified) --experimental-detect-module flag and link to cli.md added. --- doc/api/packages.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/doc/api/packages.md b/doc/api/packages.md index 9b775f40f1dedc..3e5f543e790fa0 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -69,15 +69,14 @@ expressions: * Strings passed in as an argument to `--eval`, or piped to `node` via `STDIN`, with the flag `--input-type=module`. -* Code that contains syntax that only parses successfully as [ES modules][], +* When using [--experimental-detect-module](https://nodejs.org/docs/latest/api/cli.html), + code that contains syntax that only parses successfully as [ES modules][], such as `import` or `export` statements or `import.meta`, when the code has no - explicit marker of how it should be interpreted. To use this feature - [--experimental-detect-module](https://nodejs.org/docs/latest/api/cli.html) - flag is to be used. Explicit markers are `.mjs` or `.cjs` extensions, - `package.json` `"type"` fields with either `"module"` or `"commonjs"` values, - or `--input-type` or `--experimental-default-type` flags. Dynamic `import()` - expressions are supported in either CommonJS or ES modules and would not - cause a file to be treated as an ES module. + explicit marker of how it should be interpreted. Explicit markers are `.mjs` or + `.cjs` extensions, `package.json` `"type"` fields with either `"module"` or + `"commonjs"` values, or `--input-type` or `--experimental-default-type` flags. + Dynamic `import()` expressions are supported in either CommonJS or ES modules and + would not cause a file to be treated as an ES module. Node.js will treat the following as [CommonJS][] when passed to `node` as the initial input, or when referenced by `import` statements or `import()` From e2e556a803f4850ad5ac3a1d02e5e387cb22bf3a Mon Sep 17 00:00:00 2001 From: Shubherthi Mitra <143800527+shubherthi-mitra@users.noreply.github.com> Date: Sat, 9 Dec 2023 18:51:05 +0530 Subject: [PATCH 4/5] Update packages.md added ref link Mentioned --experimental-defect-module flag in doc and added ref link to cli.md --- doc/api/packages.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/doc/api/packages.md b/doc/api/packages.md index 3e5f543e790fa0..10d2c94fbc54cf 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -69,14 +69,14 @@ expressions: * Strings passed in as an argument to `--eval`, or piped to `node` via `STDIN`, with the flag `--input-type=module`. -* When using [--experimental-detect-module](https://nodejs.org/docs/latest/api/cli.html), - code that contains syntax that only parses successfully as [ES modules][], - such as `import` or `export` statements or `import.meta`, when the code has no - explicit marker of how it should be interpreted. Explicit markers are `.mjs` or - `.cjs` extensions, `package.json` `"type"` fields with either `"module"` or - `"commonjs"` values, or `--input-type` or `--experimental-default-type` flags. - Dynamic `import()` expressions are supported in either CommonJS or ES modules and - would not cause a file to be treated as an ES module. +* When using [`--experimental-detect-module`][], code that contains syntax that + only parses successfully as [ES modules][], such as `import` or `export` + statements or `import.meta`, when the code has no explicit marker of how it + should be interpreted. Explicit markers are `.mjs` or `.cjs` extensions, + `package.json` `"type"` fields with either `"module"` or `"commonjs"` values, + or `--input-type` or `--experimental-default-type` flags. Dynamic `import()` + expressions are supported in either CommonJS or ES modules and would not + cause a file to be treated as an ES module. Node.js will treat the following as [CommonJS][] when passed to `node` as the initial input, or when referenced by `import` statements or `import()` @@ -1363,6 +1363,7 @@ This field defines [subpath imports][] for the current package. [`"type"`]: #type [`--conditions` / `-C` flag]: #resolving-user-conditions [`--experimental-default-type`]: cli.md#--experimental-default-typetype +[`--experimental-detect-module`]: cli.md#--experimental-detect-module [`--no-addons` flag]: cli.md#--no-addons [`ERR_PACKAGE_PATH_NOT_EXPORTED`]: errors.md#err_package_path_not_exported [`esm`]: https://github.com/standard-things/esm#readme From b19e147d89e7565e8ccf7a794954b015cd18b417 Mon Sep 17 00:00:00 2001 From: Shubherthi Mitra <143800527+shubherthi-mitra@users.noreply.github.com> Date: Sat, 9 Dec 2023 22:50:11 +0530 Subject: [PATCH 5/5] Updated packages.md fixed a paragraph Simplified the paragraph under the heading ###Determining module system, mentioning --experimental-detect-module flag and reference to cli.md --- doc/api/packages.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/api/packages.md b/doc/api/packages.md index 10d2c94fbc54cf..8a5efdc89c4853 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -69,12 +69,12 @@ expressions: * Strings passed in as an argument to `--eval`, or piped to `node` via `STDIN`, with the flag `--input-type=module`. -* When using [`--experimental-detect-module`][], code that contains syntax that - only parses successfully as [ES modules][], such as `import` or `export` - statements or `import.meta`, when the code has no explicit marker of how it - should be interpreted. Explicit markers are `.mjs` or `.cjs` extensions, - `package.json` `"type"` fields with either `"module"` or `"commonjs"` values, - or `--input-type` or `--experimental-default-type` flags. Dynamic `import()` +* When using [`--experimental-detect-module`][], code containing syntax only + successfully parsed as [ES modules][], such as `import` or `export` + statements or `import.meta`, having no explicit marker of how it should be + interpreted. Explicit markers are `.mjs` or `.cjs` extensions, `package.json` + `"type"` fields with either `"module"` or `"commonjs"` values, or + `--input-type` or `--experimental-default-type` flags. Dynamic `import()` expressions are supported in either CommonJS or ES modules and would not cause a file to be treated as an ES module.