Revert "esm: remove experimental status from JSON modules"

This reverts commit ec8776d.

PR-URL: #29754
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Myles Borins <myles.borins@gmail.com>

doc/api/cli.md

@@ -165,6 +165,13 @@ added: v12.7.0
 
 Enable experimental resolution using the `exports` field in `package.json`.
 
+### `--experimental-json-modules`
+<!-- YAML
+added: v12.9.0
+-->
+
+Enable experimental JSON support for the ES Module loader.
+
 ### `--experimental-modules`
 <!-- YAML
 added: v8.5.0
@@ -1019,6 +1026,7 @@ Node.js options that are allowed are:
 * `--enable-source-maps`
 * `--es-module-specifier-resolution`
 * `--experimental-exports`
+* `--experimental-json-modules`
 * `--experimental-loader`
 * `--experimental-modules`
 * `--experimental-policy`

doc/api/esm.md

@@ -587,11 +587,16 @@ syncBuiltinESMExports();
 fs.readFileSync === readFileSync;
 ```
 
-## JSON Modules
+## Experimental JSON Modules
 
-JSON modules follow the [WHATWG JSON modules specification][].
+Currently importing JSON modules are only supported in the `commonjs` mode
+and are loaded using the CJS loader. [WHATWG JSON modules specification][] are
+still being standardized, and are experimentally supported by including the
+additional flag `--experimental-json-modules` when running Node.js.
 
-The imported JSON only exposes a `default`. There is no
+When the `--experimental-json-modules` flag is included both the
+`commonjs` and `module` mode will use the new experimental JSON
+loader. The imported JSON only exposes a `default`, there is no
 support for named exports. A cache entry is created in the CommonJS
 cache, to avoid duplication. The same object will be returned in
 CommonJS if the JSON module has already been imported from the
@@ -604,6 +609,14 @@ Assuming an `index.mjs` with
 import packageConfig from './package.json';
 ```
 
+The `--experimental-json-modules` flag is needed for the module
+to work.
+
+```bash
+node --experimental-modules index.mjs # fails
+node --experimental-modules --experimental-json-modules index.mjs # works
+```
+
 ## Experimental Wasm Modules
 
 Importing Web Assembly modules is supported under the

doc/node.1

@@ -108,6 +108,9 @@ Requires Node.js to be built with
 .It Fl -es-module-specifier-resolution
 Select extension resolution algorithm for ES Modules; either 'explicit' (default) or 'node'
 .
+.It Fl -experimental-json-modules
+Enable experimental JSON interop support for the ES Module loader.
+.
 .It Fl -experimental-modules
 Enable experimental ES module support and caching modules.
 .

lib/internal/modules/esm/default_resolve.js

@@ -8,6 +8,7 @@ const { getOptionValue } = require('internal/options');
 
 const preserveSymlinks = getOptionValue('--preserve-symlinks');
 const preserveSymlinksMain = getOptionValue('--preserve-symlinks-main');
+const experimentalJsonModules = getOptionValue('--experimental-json-modules');
 const typeFlag = getOptionValue('--input-type');
 const experimentalWasmModules = getOptionValue('--experimental-wasm-modules');
 const { resolve: moduleWrapResolve,
@@ -28,22 +29,24 @@ const extensionFormatMap = {
   '__proto__': null,
   '.cjs': 'commonjs',
   '.js': 'module',
-  '.json': 'json',
   '.mjs': 'module'
 };
 
 const legacyExtensionFormatMap = {
   '__proto__': null,
   '.cjs': 'commonjs',
   '.js': 'commonjs',
-  '.json': 'json',
+  '.json': 'commonjs',
   '.mjs': 'module',
   '.node': 'commonjs'
 };
 
 if (experimentalWasmModules)
   extensionFormatMap['.wasm'] = legacyExtensionFormatMap['.wasm'] = 'wasm';
 
+if (experimentalJsonModules)
+  extensionFormatMap['.json'] = legacyExtensionFormatMap['.json'] = 'json';
+
 function resolve(specifier, parentURL) {
   try {
     const parsed = new URL(specifier);

src/node_options.cc

@@ -135,6 +135,11 @@ void EnvironmentOptions::CheckOptions(std::vector<std::string>* errors) {
     }
   }
 
+  if (experimental_json_modules && !experimental_modules) {
+    errors->push_back("--experimental-json-modules requires "
+                      "--experimental-modules be enabled");
+  }
+
   if (experimental_wasm_modules && !experimental_modules) {
     errors->push_back("--experimental-wasm-modules requires "
                       "--experimental-modules be enabled");
@@ -320,6 +325,10 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             "experimental support for exports in package.json",
             &EnvironmentOptions::experimental_exports,
             kAllowedInEnvironment);
+  AddOption("--experimental-json-modules",
+            "experimental JSON interop support for the ES Module loader",
+            &EnvironmentOptions::experimental_json_modules,
+            kAllowedInEnvironment);
   AddOption("--experimental-loader",
             "(with --experimental-modules) use the specified file as a "
             "custom loader",

src/node_options.h

@@ -102,6 +102,7 @@ class EnvironmentOptions : public Options {
   bool abort_on_uncaught_exception = false;
   bool enable_source_maps = false;
   bool experimental_exports = false;
+  bool experimental_json_modules = false;
   bool experimental_modules = false;
   std::string es_module_specifier_resolution;
   bool experimental_wasm_modules = false;

test/es-module/test-esm-json-cache.mjs

@@ -1,4 +1,4 @@
-// Flags: --experimental-modules
+// Flags: --experimental-modules --experimental-json-modules
 import '../common/index.mjs';
 
 import { strictEqual, deepStrictEqual } from 'assert';

test/es-module/test-esm-json.mjs

@@ -1,5 +1,4 @@
-// Flags: --experimental-modules
-
+// Flags: --experimental-modules --experimental-json-modules
 import '../common/index.mjs';
 import { strictEqual } from 'assert';