module: add --experimental-strip-private-modules

Signed-off-by: Marco Ippolito <marcoippolito54@gmail.com>

Author: marco-ippolito

doc/api/cli.md

@@ -1407,6 +1407,25 @@ added:
 
 Enable the experimental [`node:stream/iter`][] module.
 
+### `--experimental-strip-private-modules`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+By default, Node.js refuses to strip types from TypeScript files inside
+folders under a `node_modules` path. This flag enables type stripping for
+such files when they belong to a package whose `package.json` contains
+`"private": true`. Files belonging to non-private packages still throw
+[`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`][].
+The limitation to private packages should never be lifted,
+as publishing packages with TypeScript sources
+is highly discouraged.
+Stripping types inside `node_modules` is intended only
+for local development.
+
 ### `--experimental-test-coverage`
 
 <!-- YAML
@@ -3816,6 +3835,7 @@ one is included in the list below.
 * `--experimental-shadow-realm`
 * `--experimental-specifier-resolution`
 * `--experimental-stream-iter`
+* `--experimental-strip-private-modules`
 * `--experimental-test-isolation`
 * `--experimental-top-level-await`
 * `--experimental-vfs`
@@ -4447,6 +4467,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 [`Buffer`]: buffer.md#class-buffer
 [`CRYPTO_secure_malloc_init`]: https://www.openssl.org/docs/man3.0/man3/CRYPTO_secure_malloc_init.html
 [`ERR_INVALID_TYPESCRIPT_SYNTAX`]: errors.md#err_invalid_typescript_syntax
+[`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`]: errors.md#err_unsupported_node_modules_type_stripping
 [`ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX`]: errors.md#err_unsupported_typescript_syntax
 [`NODE_OPTIONS`]: #node_optionsoptions
 [`NODE_USE_ENV_PROXY=1`]: #node_use_env_proxy1

doc/api/packages.md

@@ -1151,6 +1151,9 @@ The following fields in `package.json` files are used in Node.js:
   limits which submodules can be loaded from within the package.
 * [`"imports"`][] - Package imports, for use by modules within the package
   itself.
+* [`"private"`][] - When `true`, marks the package as not for publication. Used
+  by [`--experimental-strip-private-modules`][] to allow type stripping for the
+  package's TypeScript files under `node_modules`.
 
 ### `"name"`
 
@@ -1346,6 +1349,30 @@ Package imports permit mapping to external packages.
 
 This field defines [subpath imports][] for the current package.
 
+### `"private"`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {boolean}
+
+```json
+{
+  "private": true
+}
+```
+
+The `"private"` field marks a package as private, signaling to package managers
+such as _npm_ that it must not be published to a public registry.
+By default, Node.js refuses to strip types from TypeScript files inside
+`node_modules`. When [`--experimental-strip-private-modules`][] is enabled,
+Node.js allows type stripping for:
+
+* files that are not descendant of a `node_modules` directory.
+* files that are descendant of a directory whose parent is a `node_modules` directory
+  and that contains a `package.json` file that sets `"private": true`.
+
 [CommonJS]: modules.md
 [Conditional exports]: #conditional-exports
 [ES module]: esm.md
@@ -1360,10 +1387,12 @@ This field defines [subpath imports][] for the current package.
 [`"imports"`]: #imports
 [`"main"`]: #main
 [`"name"`]: #name
+[`"private"`]: #private
 [`"type"`]: #type
 [`--conditions` / `-C` flag]: #resolving-user-conditions
 [`--experimental-addon-modules`]: cli.md#--experimental-addon-modules
 [`--experimental-package-map`]: cli.md#--experimental-package-mappath
+[`--experimental-strip-private-modules`]: cli.md#--experimental-strip-private-modules
 [`--no-addons` flag]: cli.md#--no-addons
 [`ERR_PACKAGE_MAP_EXTERNAL_FILE`]: errors.md#err_package_map_external_file
 [`ERR_PACKAGE_PATH_NOT_EXPORTED`]: errors.md#err_package_path_not_exported

doc/api/typescript.md

@@ -217,6 +217,15 @@ To discourage package authors from publishing packages written in TypeScript,
 Node.js refuses to handle TypeScript files inside folders under a `node_modules`
 path.
 
+The [`--experimental-strip-private-modules`][] flag relaxes this restriction
+for packages whose `package.json` contains `"private": true`, such as
+workspace packages in a monorepo, which are not published to a registry.
+The limitation to private packages should never be lifted,
+as publishing packages with TypeScript sources
+is highly discouraged.
+Stripping types inside `node_modules` is intended only
+for local development.
+
 ### Paths aliases
 
 [`tsconfig` "paths"][] won't be transformed and therefore produce an error. The closest
@@ -226,6 +235,7 @@ with `#`.
 [CommonJS]: modules.md
 [ES Modules]: esm.md
 [Full TypeScript support]: #full-typescript-support
+[`--experimental-strip-private-modules`]: cli.md#--experimental-strip-private-modules
 [`--no-strip-types`]: cli.md#--no-strip-types
 [`ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX`]: errors.md#err_unsupported_typescript_syntax
 [`tsconfig` "paths"]: https://www.typescriptlang.org/tsconfig/#paths

doc/node.1

@@ -777,6 +777,10 @@ Use this flag to enable ShadowRealm support.
 .It Fl -experimental-storage-inspection
 Enable experimental support for storage inspection
 .
+.It Fl -experimental-strip-private-modules
+Enable type-stripping for TypeScript files under node_modules belonging to
+packages whose package.json contains \fB"private": true\fR.
+.
 .It Fl -experimental-test-coverage
 When used in conjunction with the \fBnode:test\fR module, a code coverage report is
 generated as part of the test runner output. If no tests are run, a coverage

lib/internal/modules/package_json_reader.js

@@ -60,6 +60,7 @@ function deserializePackageJSON(path, contents) {
     3: plainImports,
     4: plainExports,
     5: optionalFilePath,
+    6: isPrivate,
   } = contents;
 
   const pjsonPath = optionalFilePath ?? path;
@@ -69,6 +70,7 @@ function deserializePackageJSON(path, contents) {
     ...(name != null && { name }),
     ...(main != null && { main }),
     ...(type != null && { type }),
+    ...(isPrivate != null && { private: isPrivate }),
   };
 
   if (plainExports !== null) {

lib/internal/modules/typescript.js

@@ -18,6 +18,7 @@ const {
   ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING,
   ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX,
 } = require('internal/errors').codes;
+const { getOptionValue } = require('internal/options');
 const assert = require('internal/assert');
 const {
   getCompileCacheEntry,
@@ -141,6 +142,28 @@ function stripTypeScriptTypesForCoverage(code) {
 }
 
 
+/**
+ * Whether type-stripping is allowed for files under node_modules belonging
+ * to packages whose package.json contains `"private": true`.
+ * @returns {boolean}
+ */
+const isStripPrivateModulesEnabled = getLazy(
+  () => getOptionValue('--experimental-strip-private-modules'),
+);
+
+/**
+ * Checks if the nearest parent package.json of a file marks its package
+ * as private.
+ * @param {string} filename The filename (path or file URL) of the source code.
+ * @returns {boolean} Whether the file belongs to a package with `"private": true`.
+ */
+function isInsidePrivatePackage(filename) {
+  const { getNearestParentPackageJSON } = require('internal/modules/package_json_reader');
+  const { urlToFilename } = require('internal/modules/helpers');
+  const packageJSON = getNearestParentPackageJSON(urlToFilename(filename));
+  return packageJSON?.data.private === true;
+}
+
 /**
  * Performs type-stripping to TypeScript source code internally.
  * It is used by internal loaders.
@@ -152,7 +175,10 @@ function stripTypeScriptTypesForCoverage(code) {
 function stripTypeScriptModuleTypes(source, filename, sourceURL) {
   assert(typeof source === 'string');
   if (isUnderNodeModules(filename)) {
-    throw new ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING(filename);
+    if (!isStripPrivateModulesEnabled() || !isInsidePrivatePackage(filename)) {
+      throw new ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING(filename);
+    }
+    emitExperimentalWarning('Type stripping in node_modules');
   }
   // Get a compile cache entry into the native compile cache store,
   // keyed by the filename. If the cache can already be loaded on disk,

src/node_modules.cc

@@ -21,6 +21,7 @@ namespace node {
 namespace modules {
 
 using v8::Array;
+using v8::Boolean;
 using v8::Context;
 using v8::External;
 using v8::FunctionCallbackInfo;
@@ -80,15 +81,18 @@ Local<Array> BindingData::PackageConfig::Serialize(Realm* realm) const {
                isolate, input.data(), NewStringType::kNormal, input.size())
         .ToLocalChecked();
   };
-  Local<Value> values[6] = {
+  Local<Value> values[7] = {
       name.has_value() ? ToString(*name) : Undefined(isolate),
       main.has_value() ? ToString(*main) : Undefined(isolate),
       ToString(type),
       imports.has_value() ? ToString(*imports) : Undefined(isolate),
       exports.has_value() ? ToString(*exports) : Undefined(isolate),
       ToString(file_path),
+      is_private.has_value()
+          ? Boolean::New(isolate, *is_private).As<Primitive>()
+          : Undefined(isolate),
   };
-  return Array::New(isolate, values, 6);
+  return Array::New(isolate, values, 7);
 }
 
 const BindingData::PackageConfig* BindingData::GetPackageJSON(
@@ -228,6 +232,11 @@ const BindingData::PackageConfig* BindingData::GetPackageJSON(
       if (field_value == "commonjs" || field_value == "module") {
         package_config.type = field_value;
       }
+    } else if (key == "private") {
+      bool is_private;
+      if (!value.get_bool().get(is_private)) {
+        package_config.is_private = is_private;
+      }
     } else if (key == "scripts") {
       if (value.type().get(field_type)) {
         return throw_invalid_package_config();

src/node_modules.h

@@ -33,6 +33,7 @@ class BindingData : public SnapshotableObject {
     std::optional<std::string> exports;
     std::optional<std::string> imports;
     std::optional<std::string> scripts;
+    std::optional<bool> is_private;
     std::string raw_json;
 
     v8::Local<v8::Array> Serialize(Realm* realm) const;

src/node_options.cc

@@ -1204,6 +1204,11 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             kAllowedInEnvvar,
             HAVE_AMARO);
   AddAlias("--experimental-strip-types", "--strip-types");
+  AddOption("--experimental-strip-private-modules",
+            "Type-stripping for TypeScript files under node_modules "
+            "belonging to packages marked \"private\": true",
+            &EnvironmentOptions::experimental_strip_private_modules,
+            kAllowedInEnvvar);
   AddOption("--interactive",
             "always enter the REPL even if stdin does not appear "
             "to be a terminal",

src/node_options.h

@@ -273,6 +273,7 @@ class EnvironmentOptions : public Options {
   std::vector<std::string> preload_esm_modules;
 
   bool strip_types = HAVE_AMARO;
+  bool experimental_strip_private_modules = EXPERIMENTALS_DEFAULT_VALUE;
 
   std::vector<std::string> user_argv;