module: add module.stripTypeScriptTypes

PR-URL: #55282Fixes: #54300
Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com>
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
Reviewed-By: Chemi Atlow <chemi@atlow.co.il>
Reviewed-By: Paolo Insogna <paolo@cowtech.it>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Richard Lau <rlau@redhat.com>

Author: marco-ippolito

doc/api/module.md

@@ -270,6 +270,105 @@ changes:
 Register a module that exports [hooks][] that customize Node.js module
 resolution and loading behavior. See [Customization hooks][].
 
+## `module.stripTypeScriptTypes(code[, options])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1.0 - Early development
+
+* `code` {string} The code to strip type annotations from.
+* `options` {Object}
+ * `mode` {string} **Default:** `'strip'`. Possible values are:
+ * `'strip'` Only strip type annotations without performing the transformation of TypeScript features.
+ * `'transform'` Strip type annotations and transform TypeScript features to JavaScript.
+ * `sourceMap` {boolean} **Default:** `false`. Only when `mode` is `'transform'`, if `true`, a source map
+ will be generated for the transformed code.
+ * `sourceUrl` {string} Specifies the source url used in the source map.
+* Returns: {string} The code with type annotations stripped.
+`module.stripTypeScriptTypes()` removes type annotations from TypeScript code. It
+ can be used to strip type annotations from TypeScript code before running it
+ with `vm.runInContext()` or `vm.compileFunction()`.
+ By default, it will throw an error if the code contains TypeScript features
+ that require transformation such as `Enums`,
+ see [type-stripping][] for more information.
+ When mode is `'transform'`, it also transforms TypeScript features to JavaScript,
+ see [transform TypeScript features][] for more information.
+ When mode is `'strip'`, source maps are not generated, because locations are preserved.
+ If `sourceMap` is provided, when mode is `'strip'`, an error will be thrown.
+
+_WARNING_: The output of this function should not be considered stable across Node.js versions,
+due to changes in the TypeScript parser.
+
+```mjs
+import { stripTypeScriptTypes } from'node:module';
+constcode='const a: number = 1;';
+conststrippedCode=stripTypeScriptTypes(code);
+console.log(strippedCode);
+// Prints: const a = 1;
+```
+
+```cjs
+const { stripTypeScriptTypes } =require('node:module');
+constcode='const a: number = 1;';
+conststrippedCode=stripTypeScriptTypes(code);
+console.log(strippedCode);
+// Prints: const a = 1;
+```
+
+If `sourceUrl` is provided, it will be used appended as a comment at the end of the output:
+
+```mjs
+import { stripTypeScriptTypes } from'node:module';
+constcode='const a: number = 1;';
+conststrippedCode=stripTypeScriptTypes(code, { mode:'strip', sourceUrl:'source.ts' });
+console.log(strippedCode);
+// Prints: const a = 1\n\n//# sourceURL=source.ts;
+```
+
+```cjs
+const { stripTypeScriptTypes } =require('node:module');
+constcode='const a: number = 1;';
+conststrippedCode=stripTypeScriptTypes(code, { mode:'strip', sourceUrl:'source.ts' });
+console.log(strippedCode);
+// Prints: const a = 1\n\n//# sourceURL=source.ts;
+```
+
+When `mode` is `'transform'`, the code is transformed to JavaScript:
+
+```mjs
+import { stripTypeScriptTypes } from'node:module';
+constcode=`
+ namespace MathUtil {
+ export const add = (a: number, b: number) => a + b;
+ }`;
+conststrippedCode=stripTypeScriptTypes(code, { mode:'transform', sourceMap:true });
+console.log(strippedCode);
+// Prints:
+// var MathUtil;
+// (function(MathUtil) {
+// MathUtil.add = (a, b)=>a + b;
+// })(MathUtil || (MathUtil = {}));
+// # sourceMappingURL=data:application/json;base64, ...
+```
+
+```cjs
+const { stripTypeScriptTypes } =require('node:module');
+constcode=`
+ namespace MathUtil {
+ export const add = (a: number, b: number) => a + b;
+ }`;
+conststrippedCode=stripTypeScriptTypes(code, { mode:'transform', sourceMap:true });
+console.log(strippedCode);
+// Prints:
+// var MathUtil;
+// (function(MathUtil) {
+// MathUtil.add = (a, b)=>a + b;
+// })(MathUtil || (MathUtil = {}));
+// # sourceMappingURL=data:application/json;base64, ...
+```
+
 ### `module.syncBuiltinESMExports()`
 
 <!-- YAML
@@ -1251,3 +1350,5 @@ returned object contains the following keys:
 [realm]: https://tc39.es/ecma262/#realm
 [source map include directives]: https://sourcemaps.info/spec.html#h.lmz475t4mvbx
 [transferable objects]: worker_threads.md#portpostmessagevalue-transferlist
+[transform TypeScript features]: typescript.md#typescript-features
+[type-stripping]: typescript.md#type-stripping

lib/internal/main/eval_string.js

@@ -14,8 +14,8 @@ const {
  markBootstrapComplete,
 }=require('internal/process/pre_execution');
 const{ evalModuleEntryPoint, evalScript }=require('internal/process/execution');
-const{ addBuiltinLibsToObject, stripTypeScriptTypes}=require('internal/modules/helpers');
-
+const{ addBuiltinLibsToObject }=require('internal/modules/helpers');
+const{ stripTypeScriptModuleTypes }=require('internal/modules/typescript');
 const{ getOptionValue }=require('internal/options');
 
 prepareMainThreadExecution();
@@ -24,7 +24,7 @@ markBootstrapComplete();
 
 constcode=getOptionValue('--eval');
 constsource=getOptionValue('--experimental-strip-types') ?
-stripTypeScriptTypes(code) :
+stripTypeScriptModuleTypes(code) :
 code;
 
 constprint=getOptionValue('--print');

lib/internal/modules/cjs/loader.js

@@ -151,8 +151,8 @@ const {
  setHasStartedUserCJSExecution,
  stripBOM,
  toRealPath,
- stripTypeScriptTypes,
 }=require('internal/modules/helpers');
+const{ stripTypeScriptModuleTypes }=require('internal/modules/typescript');
 constpackageJsonReader=require('internal/modules/package_json_reader');
 const{ getOptionValue, getEmbedderOptions }=require('internal/options');
 constshouldReportRequiredModules=getLazy(()=>process.env.WATCH_REPORT_DEPENDENCIES);
@@ -1357,7 +1357,7 @@ let hasPausedEntry = false;
 functionloadESMFromCJS(mod,filename){
 letsource=getMaybeCachedSource(mod,filename);
 if(getOptionValue('--experimental-strip-types')&&path.extname(filename)==='.mts'){
-source=stripTypeScriptTypes(source,filename);
+source=stripTypeScriptModuleTypes(source,filename);
 }
 constcascadedLoader=require('internal/modules/esm/loader').getOrInitializeCascadedLoader();
 constisMain=mod[kIsMainSymbol];
@@ -1599,7 +1599,7 @@ function getMaybeCachedSource(mod, filename) {
 
 functionloadCTS(module,filename){
 constsource=getMaybeCachedSource(module,filename);
-constcode=stripTypeScriptTypes(source,filename);
+constcode=stripTypeScriptModuleTypes(source,filename);
 module._compile(code,filename,'commonjs');
 }
 
@@ -1611,7 +1611,7 @@ function loadCTS(module, filename) {
 functionloadTS(module,filename){
 // If already analyzed the source, then it will be cached.
 constsource=getMaybeCachedSource(module,filename);
-constcontent=stripTypeScriptTypes(source,filename);
+constcontent=stripTypeScriptModuleTypes(source,filename);
 letformat;
 constpkg=packageJsonReader.getNearestParentPackageJSON(filename);
 // Function require shouldn't be used in ES modules.
@@ -1631,7 +1631,7 @@ function loadTS(module, filename) {
 if(Module._cache[parentPath]){
 letparentSource;
 try{
-parentSource=stripTypeScriptTypes(fs.readFileSync(parentPath,'utf8'),parentPath);
+parentSource=stripTypeScriptModuleTypes(fs.readFileSync(parentPath,'utf8'),parentPath);
 }catch{
 // Continue regardless of error.
 }

lib/internal/modules/esm/get_format.js

@@ -164,9 +164,10 @@ function getFileProtocolModuleFormat(url, context = { __proto__: null }, ignoreE
 // Since experimental-strip-types depends on detect-module, we always return null
 // if source is undefined.
 if(!source){returnnull;}
-const{ stripTypeScriptTypes, stringify }=require('internal/modules/helpers');
+const{ stringify }=require('internal/modules/helpers');
+const{ stripTypeScriptModuleTypes }=require('internal/modules/typescript');
 conststringifiedSource=stringify(source);
-constparsedSource=stripTypeScriptTypes(stringifiedSource,fileURLToPath(url));
+constparsedSource=stripTypeScriptModuleTypes(stringifiedSource,fileURLToPath(url));
 constdetectedFormat=detectModuleFormat(parsedSource,url);
 constformat=`${detectedFormat}-typescript`;
 if(format==='module-typescript'&&foundPackageJson){

lib/internal/modules/esm/translators.js

@@ -31,10 +31,10 @@ const {
  assertBufferSource,
  loadBuiltinModule,
  stringify,
- stripTypeScriptTypes,
  stripBOM,
  urlToFilename,
 }=require('internal/modules/helpers');
+const{ stripTypeScriptModuleTypes }=require('internal/modules/typescript');
 const{
  kIsCachedByESMLoader,
 Module: CJSModule,
@@ -248,7 +248,7 @@ translators.set('require-commonjs', (url, source, isMain) => {
 translators.set('require-commonjs-typescript',(url,source,isMain)=>{
 emitExperimentalWarning('Type Stripping');
 assert(cjsParse);
-constcode=stripTypeScriptTypes(stringify(source),url);
+constcode=stripTypeScriptModuleTypes(stringify(source),url);
 returncreateCJSModuleWrap(url,code);
 });
 
@@ -463,7 +463,7 @@ translators.set('wasm', async function(url, source) {
 translators.set('commonjs-typescript',function(url,source){
 emitExperimentalWarning('Type Stripping');
 assertBufferSource(source,true,'load');
-constcode=stripTypeScriptTypes(stringify(source),url);
+constcode=stripTypeScriptModuleTypes(stringify(source),url);
 debug(`Translating TypeScript ${url}`);
 returnFunctionPrototypeCall(translators.get('commonjs'),this,url,code,false);
 });
@@ -472,7 +472,7 @@ translators.set('commonjs-typescript', function(url, source) {
 translators.set('module-typescript',function(url,source){
 emitExperimentalWarning('Type Stripping');
 assertBufferSource(source,true,'load');
-constcode=stripTypeScriptTypes(stringify(source),url);
+constcode=stripTypeScriptModuleTypes(stringify(source),url);
 debug(`Translating TypeScript ${url}`);
 returnFunctionPrototypeCall(translators.get('module'),this,url,code,false);
 });

lib/internal/modules/helpers.js

@@ -15,8 +15,6 @@ const {
 const{
 ERR_INVALID_ARG_TYPE,
 ERR_INVALID_RETURN_PROPERTY_VALUE,
-ERR_INVALID_TYPESCRIPT_SYNTAX,
-ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING,
 }=require('internal/errors').codes;
 const{ BuiltinModule }=require('internal/bootstrap/realm');
 
@@ -27,9 +25,8 @@ const path = require('path');
 const{ pathToFileURL, fileURLToPath }=require('internal/url');
 constassert=require('internal/assert');
 
-const{ Buffer }=require('buffer');
 const{ getOptionValue }=require('internal/options');
-const{assertTypeScript,setOwnProperty, getLazy, isUnderNodeModules}=require('internal/util');
+const{ setOwnProperty, getLazy }=require('internal/util');
 const{ inspect }=require('internal/util/inspect');
 
 constlazyTmpdir=getLazy(()=>require('os').tmpdir());
@@ -314,74 +311,6 @@ function getBuiltinModule(id) {
 returnnormalizedId ? require(normalizedId) : undefined;
 }
 
-/**
- * The TypeScript parsing mode, either 'strip-only' or 'transform'.
- * @type {string}
- */
-constgetTypeScriptParsingMode=getLazy(()=>
-(getOptionValue('--experimental-transform-types') ? 'transform' : 'strip-only'),
-);
-
-/**
- * Load the TypeScript parser.
- * and returns an object with a `code` property.
- * @returns {Function} The TypeScript parser function.
- */
-constloadTypeScriptParser=getLazy(()=>{
-assertTypeScript();
-constamaro=require('internal/deps/amaro/dist/index');
-returnamaro.transformSync;
-});
-
-/**
- *
- * @param {string} source the source code
- * @param {object} options the options to pass to the parser
- * @returns {TransformOutput} an object with a `code` property.
- */
-functionparseTypeScript(source,options){
-constparse=loadTypeScriptParser();
-try{
-returnparse(source,options);
-}catch(error){
-thrownewERR_INVALID_TYPESCRIPT_SYNTAX(error);
-}
-}
-
-/**
- * @typedef {object} TransformOutput
- * @property {string} code The compiled code.
- * @property {string} [map] The source maps (optional).
- *
- * Performs type-stripping to TypeScript source code.
- * @param {string} source TypeScript code to parse.
- * @param {string} filename The filename of the source code.
- * @returns {TransformOutput} The stripped TypeScript code.
- */
-functionstripTypeScriptTypes(source,filename){
-if(isUnderNodeModules(filename)){
-thrownewERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING(filename);
-}
-assert(typeofsource==='string');
-constoptions={
-__proto__: null,
-mode: getTypeScriptParsingMode(),
-sourceMap: getOptionValue('--enable-source-maps'),
- filename,
-};
-const{ code, map }=parseTypeScript(source,options);
-if(map){
-// TODO(@marco-ippolito) When Buffer.transcode supports utf8 to
-// base64 transformation, we should change this line.
-constbase64SourceMap=Buffer.from(map).toString('base64');
-return`${code}\n\n//# sourceMappingURL=data:application/json;base64,${base64SourceMap}`;
-}
-// Source map is not necessary in strip-only mode. However, to map the source
-// file in debuggers to the original TypeScript source, add a sourceURL magic
-// comment to hint that it is a generated source.
-return`${code}\n\n//# sourceURL=${filename}`;
-}
-
 /** @type {import('internal/util/types')} */
 let_TYPES=null;
 /**
@@ -485,7 +414,6 @@ module.exports = {
  loadBuiltinModule,
  makeRequireFunction,
  normalizeReferrerURL,
- stripTypeScriptTypes,
  stringify,
  stripBOM,
  toRealPath,