| | |
| | | /** |
| | | * The `node:vm` module enables compiling and running code within V8 Virtual |
| | | * Machine contexts. |
| | | * |
| | | * **The `node:vm` module is not a security** |
| | | * **mechanism. Do not use it to run untrusted code.** |
| | | * |
| | | * JavaScript code can be compiled and run immediately or |
| | | * compiled, saved, and run later. |
| | | * |
| | | * A common use case is to run the code in a different V8 Context. This means |
| | | * invoked code has a different global object than the invoking code. |
| | | * |
| | | * One can provide the context by `contextifying` an |
| | | * object. The invoked code treats any property in the context like a |
| | | * global variable. Any changes to global variables caused by the invoked |
| | | * code are reflected in the context object. |
| | | * |
| | | * ```js |
| | | * import vm from 'node:vm'; |
| | | * |
| | | * const x = 1; |
| | | * |
| | | * const context = { x: 2 }; |
| | | * vm.createContext(context); // Contextify the object. |
| | | * |
| | | * const code = 'x += 40; var y = 17;'; |
| | | * // `x` and `y` are global variables in the context. |
| | | * // Initially, x has the value 2 because that is the value of context.x. |
| | | * vm.runInContext(code, context); |
| | | * |
| | | * console.log(context.x); // 42 |
| | | * console.log(context.y); // 17 |
| | | * |
| | | * console.log(x); // 1; y is not defined. |
| | | * ``` |
| | | * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/vm.js) |
| | | */ |
| | | declare module "node:vm" { |
| | | import { NonSharedBuffer } from "node:buffer"; |
| | | import { ImportAttributes, ImportPhase } from "node:module"; |
| | |
| | | * // "contextifiedObject" when creating the context. |
| | | * export default secret; |
| | | * `, { context: referencingModule.context }); |
| | | * moduleMap.set(specifier, linkedModule); |
| | | * moduleMap.set(specifier, requestedModule); |
| | | * // Resolve the dependencies of the new module as well. |
| | | * resolveAndLinkDependencies(requestedModule); |
| | | * } |
| | |
| | | */ |
| | | status: ModuleStatus; |
| | | /** |
| | | * Evaluate the module. |
| | | * Evaluate the module and its depenendencies. Corresponds to the [Evaluate() concrete method](https://tc39.es/ecma262/#sec-moduleevaluation) field of |
| | | * [Cyclic Module Record](https://tc39.es/ecma262/#sec-cyclic-module-records)s in the ECMAScript specification. |
| | | * |
| | | * This must be called after the module has been linked; otherwise it will reject. |
| | | * It could be called also when the module has already been evaluated, in which |
| | | * case it will either do nothing if the initial evaluation ended in success |
| | | * (`module.status` is `'evaluated'`) or it will re-throw the exception that the |
| | | * initial evaluation resulted in (`module.status` is `'errored'`). |
| | | * If the module is a `vm.SourceTextModule`, `evaluate()` must be called after the module has been instantiated; |
| | | * otherwise `evaluate()` will return a rejected promise. |
| | | * |
| | | * This method cannot be called while the module is being evaluated |
| | | * (`module.status` is `'evaluating'`). |
| | | * For a `vm.SourceTextModule`, the promise returned by `evaluate()` may be fulfilled either |
| | | * synchronously or asynchronously: |
| | | * |
| | | * Corresponds to the [Evaluate() concrete method](https://tc39.es/ecma262/#sec-moduleevaluation) field of [Cyclic Module Record](https://tc39.es/ecma262/#sec-cyclic-module-records) s in the |
| | | * ECMAScript specification. |
| | | * 1. If the `vm.SourceTextModule` has no top-level `await` in itself or any of its dependencies, the promise will be |
| | | * fulfilled _synchronously_ after the module and all its dependencies have been evaluated. |
| | | * 1. If the evaluation succeeds, the promise will be _synchronously_ resolved to `undefined`. |
| | | * 2. If the evaluation results in an exception, the promise will be _synchronously_ rejected with the exception |
| | | * that causes the evaluation to fail, which is the same as `module.error`. |
| | | * 2. If the `vm.SourceTextModule` has top-level `await` in itself or any of its dependencies, the promise will be |
| | | * fulfilled _asynchronously_ after the module and all its dependencies have been evaluated. |
| | | * 1. If the evaluation succeeds, the promise will be _asynchronously_ resolved to `undefined`. |
| | | * 2. If the evaluation results in an exception, the promise will be _asynchronously_ rejected with the exception |
| | | * that causes the evaluation to fail. |
| | | * |
| | | * If the module is a `vm.SyntheticModule`, `evaluate()` always returns a promise that fulfills synchronously, see |
| | | * the specification of [Evaluate() of a Synthetic Module Record](https://tc39.es/ecma262/#sec-smr-Evaluate): |
| | | * |
| | | * 1. If the `evaluateCallback` passed to its constructor throws an exception synchronously, `evaluate()` returns |
| | | * a promise that will be synchronously rejected with that exception. |
| | | * 2. If the `evaluateCallback` does not throw an exception, `evaluate()` returns a promise that will be |
| | | * synchronously resolved to `undefined`. |
| | | * |
| | | * The `evaluateCallback` of a `vm.SyntheticModule` is executed synchronously within the `evaluate()` call, and its |
| | | * return value is discarded. This means if `evaluateCallback` is an asynchronous function, the promise returned by |
| | | * `evaluate()` will not reflect its asynchronous behavior, and any rejections from an asynchronous |
| | | * `evaluateCallback` will be lost. |
| | | * |
| | | * `evaluate()` could also be called again after the module has already been evaluated, in which case: |
| | | * |
| | | * 1. If the initial evaluation ended in success (`module.status` is `'evaluated'`), it will do nothing |
| | | * and return a promise that resolves to `undefined`. |
| | | * 2. If the initial evaluation resulted in an exception (`module.status` is `'errored'`), it will re-reject |
| | | * the exception that the initial evaluation resulted in. |
| | | * |
| | | * This method cannot be called while the module is being evaluated (`module.status` is `'evaluating'`). |
| | | * @return Fulfills with `undefined` upon success. |
| | | */ |
| | | evaluate(options?: ModuleEvaluateOptions): Promise<void>; |