typings: lib/internal/vm.js

PR-URL: #50112 Reviewed-By: Yagiz Nizipli <[email protected]> Reviewed-By: Chengzhong Wu <[email protected]> Reviewed-By: Franziska Hinkelmann <[email protected]> Reviewed-By: Joyee Cheung <[email protected]> Reviewed-By: Rich Trott <[email protected]>

Author: GeoffreyBooth

lib/internal/vm.js

@@ -31,10 +31,23 @@ const{
 },
 }=internalBinding('util');
 
+/**
+ * Checks if the given object is a context object.
+ * @param{object} object - The object to check.
+ * @returns{boolean} - Returns true if the object is a context object, else false.
+ */
 functionisContext(object){
 returnobject[contextify_context_private_symbol]!==undefined;
 }
 
+/**
+ * Retrieves the host-defined option ID based on the provided importModuleDynamically and hint.
+ * @param{import('internal/modules/esm/utils').ImportModuleDynamicallyCallback | undefined} importModuleDynamically -
+ * The importModuleDynamically function or undefined.
+ * @param{string} hint - The hint for the option ID.
+ * @returns{symbol | import('internal/modules/esm/utils').ImportModuleDynamicallyCallback} - The host-defined option
+ * ID.
+ */
 functiongetHostDefinedOptionId(importModuleDynamically,hint){
 if(importModuleDynamically===vm_dynamic_import_main_context_default||
 importModuleDynamically===vm_dynamic_import_default_internal){
@@ -66,6 +79,12 @@ function getHostDefinedOptionId(importModuleDynamically, hint){
 returnSymbol(hint);
 }
 
+/**
+ * Registers a dynamically imported module for customization.
+ * @param{string} referrer - The path of the referrer module.
+ * @param{import('internal/modules/esm/utils').ImportModuleDynamicallyCallback} importModuleDynamically - The
+ * dynamically imported module function to be registered.
+ */
 functionregisterImportModuleDynamically(referrer,importModuleDynamically){
 // If it's undefined or certain known symbol, there's no customization so
 // no need to register anything.
@@ -83,6 +102,25 @@ function registerImportModuleDynamically(referrer, importModuleDynamically){
 });
 }
 
+/**
+ * Compiles a function from the given code string.
+ * @param{string} code - The code string to compile.
+ * @param{string} filename - The filename to use for the compiled function.
+ * @param{number} lineOffset - The line offset to use for the compiled function.
+ * @param{number} columnOffset - The column offset to use for the compiled function.
+ * @param{Buffer} [cachedData=undefined] - The cached data to use for the compiled function.
+ * @param{boolean} produceCachedData - Whether to produce cached data for the compiled function.
+ * @param{ReturnType<import('vm').createContext} [parsingContext=undefined] - The parsing context to use for the
+ * compiled function.
+ * @param{object[]} [contextExtensions=[]] - An array of context extensions to use for the compiled function.
+ * @param{string[]} [params] - An optional array of parameter names for the compiled function.
+ * @param{symbol} hostDefinedOptionId - A symbol referenced by the field `host_defined_option_symbol`.
+ * @param{import('internal/modules/esm/utils').ImportModuleDynamicallyCallback} [importModuleDynamically] -
+ * A function to use for dynamically importing modules.
+ * @returns{object} An object containing the compiled function and any associated data.
+ * @throws{TypeError} If any of the arguments are of the wrong type.
+ * @throws{ERR_INVALID_ARG_TYPE} If the parsing context is not a valid context object.
+ */
 functioninternalCompileFunction(
 code,filename,lineOffset,columnOffset,
 cachedData,produceCachedData,parsingContext,contextExtensions,
@@ -117,6 +155,19 @@ function internalCompileFunction(
 returnresult;
 }
 
+/**
+ * Creates a contextify script.
+ * @param{string} code - The code of the script.
+ * @param{string} filename - The filename of the script.
+ * @param{number} lineOffset - The line offset of the script.
+ * @param{number} columnOffset - The column offset of the script.
+ * @param{Buffer} cachedData - The cached data of the script.
+ * @param{boolean} produceCachedData - Indicates whether to produce cached data.
+ * @param{object} parsingContext - The parsing context of the script.
+ * @param{number} hostDefinedOptionId - The host-defined option ID.
+ * @param{boolean} importModuleDynamically - Indicates whether to import modules dynamically.
+ * @returns{ContextifyScript} The created contextify script.
+ */
 functionmakeContextifyScript(code,
 filename,
 lineOffset,
@@ -147,8 +198,13 @@ function makeContextifyScript(code,
 returnscript;
 }
 
-// Internal version of vm.Script.prototype.runInThisContext() which skips
-// argument validation.
+/**
+ * Runs a script in the current context.
+ * Internal version of `vm.Script.prototype.runInThisContext()` which skips argument validation.
+ * @param{ReturnType<makeContextifyScript>} script - The script to run.
+ * @param{boolean} displayErrors - Whether to display errors.
+ * @param{boolean} breakOnFirstLine - Whether to break on the first line.
+ */
 functionrunScriptInThisContext(script,displayErrors,breakOnFirstLine){
 returnReflectApply(
 runInContext,