new vm.Script(code[, options])

• code <string> Код JavaScript для компиляции.
• options <Object> | <string>
  • filename <string> Задаёт имя файла, используемое в трассировках стека, создаваемых этим сценарием. По умолчанию: 'evalmachine.<anonymous>'.
  • lineOffset <number> Задаёт смещение номера строки, отображаемое в трассировках стека, создаваемых этим сценарием. По умолчанию: 0.
  • columnOffset <number> Задаёт смещение номера столбца первой строки, отображаемое в трассировках стека, создаваемых этим сценарием. По умолчанию: 0.
  • cachedData <Buffer> | <TypedArray> | <DataView> Предоставляет необязательный Buffer или TypedArray либо DataView с данными кэша кода V8 для предоставленного исходного кода. Если значение задано, значение cachedDataRejected будет установлено в true или false в зависимости от того, принимает ли V8 эти данные.
  • produceCachedData <boolean> Если задано true и отсутствует cachedData, V8 попытается создать данные кэша кода для code. В случае успеха будет создан Buffer с данными кэша кода V8 и сохранён в свойстве cachedData возвращённого экземпляра vm.Script. Значение cachedDataProduced будет установлено в true или false в зависимости от того, удалось ли создать данные кэша кода. Этот параметр устарел; вместо него следует использовать script.createCachedData(). По умолчанию: false.
  • importModuleDynamically <Function> | <vm.constants.USE_MAIN_CONTEXT_DEFAULT_LOADER> Используется для задания способа загрузки модулей при вычислении этого сценария, когда вызывается import(). Этот параметр входит в экспериментальный API модулей. Не рекомендуется использовать его в производственной среде. Подробную информацию см. в разделе Поддержка динамического import() в API компиляции.

Если options — строка, она задаёт имя файла.

Создание нового объекта vm.Script компилирует code, но не выполняет его. Скомпилированный vm.Script впоследствии можно выполнять несколько раз. code не привязывается к глобальному объекту; вместо этого он привязывается перед каждым запуском, только на время этого запуска.

script.cachedDataRejected

• Тип: <boolean> | <undefined>

Если при создании vm.Script было передано значение cachedData, это значение будет установлено в true или false в зависимости от того, принимает ли V8 эти данные. В противном случае значение равно undefined.

script.createCachedData()

• Возвращает: <Buffer>

Создаёт кэш кода, который можно использовать с параметром cachedData конструктора Script. Возвращает Buffer. Этот метод можно вызывать в любое время и любое количество раз.

Кэш кода Script не содержит состояний, наблюдаемых из JavaScript. Кэш кода безопасно сохранять вместе с исходным кодом сценария и многократно использовать для создания новых экземпляров Script.

Функции в исходном коде Script могут быть помечены для отложенной компиляции и не компилируются при создании Script. Эти функции будут скомпилированы при первом вызове. Кэш кода сериализует метаданные, известные V8 на данный момент о Script, которые можно использовать для ускорения последующих компиляций.

const script = new vm.Script(`
function add(a, b) {
  return a + b;
}

const x = add(1, 2);
`);

const cacheWithoutAdd = script.createCachedData();
// In `cacheWithoutAdd` the function `add()` is marked for full compilation
// upon invocation.

script.runInThisContext();

const cacheWithAdd = script.createCachedData();
// `cacheWithAdd` contains fully compiled function `add()`. copy

script.runInContext(contextifiedObject[, options])

• contextifiedObject <Object> Контекстуализированный объект, возвращённый методом vm.createContext().
• options <Object>
  • displayErrors <boolean> Если задано true и при компиляции code возникает Error, строка кода, вызвавшая ошибку, добавляется в трассировку стека. По умолчанию: true.
  • timeout <integer> Задаёт количество миллисекунд, в течение которых будет выполняться code до прекращения выполнения. Если выполнение будет прекращено, будет выброшено исключение Error. Значение должно быть строго положительным целым числом.
  • breakOnSigint <boolean> Если задано true, получение SIGINT (Ctrl+C) прекратит выполнение и вызовет исключение Error. Обработчики события, ранее добавленные с помощью process.on('SIGINT'), отключаются на время выполнения сценария, но продолжают работать после его завершения. По умолчанию: false.
• Возвращает: <any> результат последнего выполненного в сценарии оператора.

Выполняет скомпилированный код, содержащийся в объекте vm.Script, в указанном contextifiedObject и возвращает результат. Выполняемый код не имеет доступа к локальной области видимости.

В следующем примере компилируется код, который увеличивает значение глобальной переменной и задаёт значение другой глобальной переменной, а затем выполняет этот код несколько раз. Глобальные переменные находятся в объекте context.

const vm = require('node:vm');

const context = {
  animal: 'cat',
  count: 2,
};

const script = new vm.Script('count += 1; name = "kitty";');

vm.createContext(context);
for (let i = 0; i < 10; ++i) {
  script.runInContext(context);
}

console.log(context);
// Prints: { animal: 'cat', count: 12, name: 'kitty' } copy

Использование параметров timeout или breakOnSigint приведёт к запуску новых циклов событий и соответствующих потоков, что повлечёт ненулевые накладные расходы.

script.runInNewContext([contextObject[, options]])

• contextObject <Object> | <vm.constants.DONT_CONTEXTIFY> | <undefined> Либо vm.constants.DONT_CONTEXTIFY, либо объект, который будет контекстуализирован. Если задано undefined, для обратной совместимости будет создан пустой контекстуализированный объект.
• options <Object>
  • displayErrors <boolean> Если задано true и при компиляции code возникает Error, строка кода, вызвавшая ошибку, добавляется в трассировку стека. По умолчанию: true.
  • timeout <integer> Задаёт количество миллисекунд, в течение которых будет выполняться code до прекращения выполнения. Если выполнение будет прекращено, будет выброшено исключение Error. Значение должно быть строго положительным целым числом.
  • breakOnSigint <boolean> Если задано true, получение SIGINT (Ctrl+C) прекратит выполнение и вызовет исключение Error. Обработчики события, ранее добавленные с помощью process.on('SIGINT'), отключаются на время выполнения сценария, но продолжают работать после его завершения. По умолчанию: false.
  • contextName <string> Удобочитаемое имя вновь созданного контекста. По умолчанию: 'VM Context i', где i — возрастающий числовой индекс созданного контекста.
  • contextOrigin <string> Источник, соответствующий вновь созданному контексту и используемый для отображения. Источник должен быть оформлен как URL, но содержать только схему, хост и порт (при необходимости), как значение свойства url.origin объекта URL. В частности, эта строка не должна содержать завершающую косую черту, так как она обозначает путь. По умолчанию: ''.
  • contextCodeGeneration <Object>
    • strings <boolean> Если задано значение false, любые вызовы eval или конструкторов функций (Function, GeneratorFunction и т. д.) вызовут EvalError. По умолчанию: true.
    • wasm <boolean> Если задано значение false, любая попытка скомпилировать модуль WebAssembly вызовет WebAssembly.CompileError. По умолчанию: true.
  • microtaskMode <string> Если задано значение afterEvaluate, микрозадачи (задачи, запланированные с помощью Promise и async function) будут выполняться сразу после выполнения сценария. В этом случае они входят в области видимости timeout и breakOnSigint.
• Возвращает: <any> результат последнего выполненного в сценарии оператора.

Этот метод является сокращением для script.runInContext(vm.createContext(options), options). Он выполняет сразу несколько действий:

1. Создаёт новый контекст.
2. Если contextObject — объект, он контекстуализируется в новом контексте. Если contextObject не определён, создаётся новый объект и контекстуализируется. Если contextObject — это vm.constants.DONT_CONTEXTIFY, ничего не контекстуализируйте.
3. Выполняет скомпилированный код, содержащийся в объекте vm.Script, в созданном контексте. Код не имеет доступа к области видимости, в которой вызван этот метод.
4. Возвращает результат.

В следующем примере компилируется код, который задаёт глобальную переменную, а затем выполняет этот код несколько раз в разных контекстах. Глобальные переменные задаются и хранятся в каждом отдельном объекте context.

const vm = require('node:vm');

const script = new vm.Script('globalVar = "set"');

const contexts = [{}, {}, {}];
contexts.forEach((context) => {
  script.runInNewContext(context);
});

console.log(contexts);
// Prints: [{ globalVar: 'set' }, { globalVar: 'set' }, { globalVar: 'set' }]

// This would throw if the context is created from a contextified object.
// vm.constants.DONT_CONTEXTIFY allows creating contexts with ordinary
// global objects that can be frozen.
const freezeScript = new vm.Script('Object.freeze(globalThis); globalThis;');
const frozenContext = freezeScript.runInNewContext(vm.constants.DONT_CONTEXTIFY); copy

script.runInThisContext([options])

• options <Object>
  • displayErrors <boolean> Если задано true и при компиляции code возникает Error, строка кода, вызвавшая ошибку, добавляется в трассировку стека. По умолчанию: true.
  • timeout <integer> Задаёт количество миллисекунд, в течение которых будет выполняться code до прекращения выполнения. Если выполнение будет прекращено, будет выброшено исключение Error. Значение должно быть строго положительным целым числом.
  • breakOnSigint <boolean> Если задано true, получение SIGINT (Ctrl+C) прекратит выполнение и вызовет исключение Error. Обработчики события, ранее добавленные с помощью process.on('SIGINT'), отключаются на время выполнения сценария, но продолжают работать после его завершения. По умолчанию: false.
• Возвращает: <any> результат последнего выполненного в сценарии оператора.

Выполняет скомпилированный код, содержащийся в vm.Script, в контексте текущего объекта global. Выполняемый код не имеет доступа к локальной области видимости, но имеет доступ к текущему объекту global.

В следующем примере компилируется код, который увеличивает переменную global, а затем выполняет этот код несколько раз:

const vm = require('node:vm');

global.globalVar = 0;

const script = new vm.Script('globalVar += 1', { filename: 'myfile.vm' });

for (let i = 0; i < 1000; ++i) {
  script.runInThisContext();
}

console.log(globalVar);

// 1000 copy

script.sourceMapURL

• Тип: <string> | <undefined>

Если сценарий скомпилирован из исходного кода, содержащего специальный комментарий с картой исходного кода, этому свойству будет присвоен URL карты исходного кода.

import vm from 'node:vm';

const script = new vm.Script(`
function myFunc() {}
//# sourceMappingURL=sourcemap.json
`);

console.log(script.sourceMapURL);
// Prints: sourcemap.json

const vm = require('node:vm');

const script = new vm.Script(`
function myFunc() {}
//# sourceMappingURL=sourcemap.json
`);

console.log(script.sourceMapURL);
// Prints: sourcemap.json

module.error

• Тип: <any>

Если module.status имеет значение 'errored', это свойство содержит исключение, выброшенное модулем во время вычисления. Если статус имеет любое другое значение, обращение к этому свойству приведет к выбросу исключения.

Значение undefined нельзя использовать в случаях, когда исключение не было выброшено, из-за возможной неоднозначности с throw undefined;.

Соответствует полю [[EvaluationError]] циклических записей модулей в спецификации ECMAScript.

module.evaluate([options])

• options <Object>
  • timeout <integer> Задает количество миллисекунд, в течение которых выполняется вычисление до завершения исполнения. Если выполнение прервано, будет выброшен объект Error. Значение должно быть строго положительным целым числом.
  • breakOnSigint <boolean> Если true, получение SIGINT (Ctrl+C) завершит выполнение и выбросит объект Error. Существующие обработчики события, добавленные с помощью process.on('SIGINT'), отключаются во время выполнения скрипта, но продолжают работать после этого. По умолчанию: false.
• Возвращает: <Promise> При успешном выполнении разрешается значением undefined.

Вычисляет модуль и его зависимости. Соответствует полю конкретного метода Evaluate() циклических записей модулей в спецификации ECMAScript.

Если модуль является vm.SourceTextModule, evaluate() необходимо вызвать после инстанцирования модуля; в противном случае evaluate() вернет отклоненный промис.

Для vm.SourceTextModule промис, возвращаемый evaluate(), может быть выполнен либо синхронно, либо асинхронно:

1. Если в самом vm.SourceTextModule или любой из его зависимостей нет выражений верхнего уровня await, промис будет выполнен синхронно после вычисления модуля и всех его зависимостей.
   1. Если вычисление выполнится успешно, промис будет синхронно разрешен значением undefined.
   2. Если при вычислении возникнет исключение, промис будет синхронно отклонен с исключением, из-за которого вычисление завершилось неудачей; это то же исключение, что и module.error.
2. Если в самом vm.SourceTextModule или любой из его зависимостей есть выражения верхнего уровня await, промис будет выполнен асинхронно после вычисления модуля и всех его зависимостей.
   1. Если вычисление выполнится успешно, промис будет асинхронно разрешен значением undefined.
   2. Если при вычислении возникнет исключение, промис будет асинхронно отклонен с исключением, из-за которого вычисление завершилось неудачей.

Если модуль является vm.SyntheticModule, evaluate() всегда возвращает промис, который выполняется синхронно; см. спецификацию Evaluate() для записи синтетического модуля:

1. Если evaluateCallback, переданный конструктору, синхронно выбрасывает исключение, evaluate() возвращает промис, который будет синхронно отклонен с этим исключением.
2. Если evaluateCallback не выбрасывает исключение, evaluate() возвращает промис, который будет синхронно разрешен значением undefined.

evaluateCallback для vm.SyntheticModule выполняется синхронно в рамках вызова evaluate(), а возвращаемое значение отбрасывается. Это означает, что если evaluateCallback является асинхронной функцией, промис, возвращаемый evaluate(), не будет отражать ее асинхронное поведение, а любые отклонения, вызванные асинхронным evaluateCallback, будут потеряны.

evaluate() также можно вызвать повторно после вычисления модуля. В этом случае:

1. Если первоначальное вычисление завершилось успешно (module.status имеет значение 'evaluated'), метод ничего не сделает и вернет промис, разрешаемый значением undefined.
2. Если первоначальное вычисление привело к исключению (module.status имеет значение 'errored'), будет повторно выброшено исключение, возникшее при первоначальном вычислении.

Этот метод нельзя вызвать во время вычисления модуля (module.status имеет значение 'evaluating').

module.identifier

• Тип: <string>

Идентификатор текущего модуля, заданный в конструкторе.

module.link(linker)

• linker <Function>

  • specifier <string> Спецификатор запрашиваемого модуля:

    import foo from 'foo';
    //              ^^^^^ the module specifier copy

  • referencingModule <vm.Module> Объект Module, для которого вызывается link().

  • extra <Object>

    • attributes <Object> Данные атрибута:

      import foo from 'foo' with { name: 'value' };
      //                         ^^^^^^^^^^^^^^^^^ the attribute copy

      Согласно ECMA-262, ожидается, что среды выполнения будут вызывать ошибку при наличии неподдерживаемого атрибута.
    • assert <Object> Псевдоним для extra.attributes.

  • Возвращает: <vm.Module> | <Promise>

• Возвращает: <Promise>

Связывает зависимости модуля. Этот метод необходимо вызвать до вычисления; его можно вызвать только один раз для каждого модуля.

Используйте sourceTextModule.linkRequests(modules) и sourceTextModule.instantiate(), чтобы связывать модули синхронно или асинхронно.

Ожидается, что функция вернет объект Module или Promise, который в конечном итоге разрешится объектом Module. Возвращаемый Module должен удовлетворять следующим двум инвариантам:

• Он должен принадлежать тому же контексту, что и родительский Module.
• Его status не должно иметь значение 'errored'.

Если status у возвращенного Module имеет значение 'unlinked', этот метод будет рекурсивно вызван для возвращенного Module с той же переданной функцией linker.

link() возвращает Promise, который будет разрешен, когда все экземпляры связывания разрешатся в допустимый Module, или отклонен, если функция связывания выбросит исключение либо вернет недопустимый Module.

Функция связывания приблизительно соответствует определенной реализацией абстрактной операции HostResolveImportedModule в спецификации ECMAScript, но имеет несколько ключевых отличий:

• Функция связывания может быть асинхронной, тогда как HostResolveImportedModule является синхронной.

Фактическая реализация HostResolveImportedModule, используемая при связывании модулей, возвращает модули, связанные в процессе связывания. Поскольку к этому моменту все модули уже будут полностью связаны, согласно спецификации реализация HostResolveImportedModule полностью синхронна.

Соответствует полю конкретного метода Link() циклических записей модулей в спецификации ECMAScript.

module.namespace

• Тип: <Object>

Объект пространства имен модуля. Доступен только после завершения связывания (module.link()).

Соответствует абстрактной операции GetModuleNamespace в спецификации ECMAScript.

module.status

• Тип: <string>

Текущий статус модуля. Возможны следующие значения:

• 'unlinked': module.link() еще не вызывался.

• 'linking': module.link() был вызван, но еще не все промисы, возвращенные функцией связывания, разрешились.

• 'linked': Модуль успешно связан, и все его зависимости связаны, но module.evaluate() еще не вызывался.

• 'evaluating': Модуль вычисляется посредством module.evaluate() для него самого или родительского модуля.

• 'evaluated': Модуль успешно вычислен.

• 'errored': Модуль вычислен, но было выброшено исключение.

За исключением 'errored', эта строка статуса соответствует полю [[Status]] циклической записи модуля в спецификации. 'errored' соответствует 'evaluated' в спецификации, но при этом [[EvaluationError]] задано значение, отличное от undefined.

new vm.SourceTextModule(code[, options])

• code <string> Код модуля JavaScript для разбора
• options
  • identifier <string> Строка, используемая в трассировках стека. По умолчанию: 'vm:module(i)', где i — возрастающий индекс, зависящий от контекста.
  • cachedData <Buffer> | <TypedArray> | <DataView> Предоставляет необязательный Buffer или TypedArray либо DataView с данными кэша кода V8 для указанного исходного кода. code должен совпадать с модулем, из которого был создан этот cachedData.
  • context <Object> Объект, преобразованный в контекст, как возвращаемый методом vm.createContext(), в котором следует скомпилировать и вычислить этот Module. Если контекст не указан, модуль вычисляется в текущем контексте выполнения.
  • lineOffset <integer> Задает смещение номера строки, отображаемое в трассировках стека, создаваемых этим Module. По умолчанию: 0.
  • columnOffset <integer> Задает смещение номера столбца первой строки, отображаемое в трассировках стека, создаваемых этим Module. По умолчанию: 0.
  • initializeImportMeta <Function> Вызывается во время вычисления этого Module для инициализации import.meta.
    • meta <import.meta>
    • module <vm.SourceTextModule>
  • importModuleDynamically <Function> Используется для задания способа загрузки модулей во время вычисления этого модуля при вызове import(). Этот параметр является частью экспериментального API модулей. Не рекомендуется использовать его в рабочей среде. Подробные сведения см. в разделе Поддержка динамического import() в API компиляции.

Создает новый экземпляр SourceTextModule.

Объекты, присвоенные свойствам объекта import.meta, могут позволить модулю получить доступ к информации за пределами указанного context. Используйте vm.runInContext(), чтобы создавать объекты в определенном контексте.

import vm from 'node:vm';

const contextifiedObject = vm.createContext({ secret: 42 });

const module = new vm.SourceTextModule(
  'Object.getPrototypeOf(import.meta.prop).secret = secret;',
  {
    initializeImportMeta(meta) {
      // Note: this object is created in the top context. As such,
      // Object.getPrototypeOf(import.meta.prop) points to the
      // Object.prototype in the top context rather than that in
      // the contextified object.
      meta.prop = {};
    },
  });
// The module has an empty `moduleRequests` array.
module.linkRequests([]);
module.instantiate();
await module.evaluate();

// Now, Object.prototype.secret will be equal to 42.
//
// To fix this problem, replace
//     meta.prop = {};
// above with
//     meta.prop = vm.runInContext('{}', contextifiedObject);

const vm = require('node:vm');
const contextifiedObject = vm.createContext({ secret: 42 });
(async () => {
  const module = new vm.SourceTextModule(
    'Object.getPrototypeOf(import.meta.prop).secret = secret;',
    {
      initializeImportMeta(meta) {
        // Note: this object is created in the top context. As such,
        // Object.getPrototypeOf(import.meta.prop) points to the
        // Object.prototype in the top context rather than that in
        // the contextified object.
        meta.prop = {};
      },
    });
  // The module has an empty `moduleRequests` array.
  module.linkRequests([]);
  module.instantiate();
  await module.evaluate();
  // Now, Object.prototype.secret will be equal to 42.
  //
  // To fix this problem, replace
  //     meta.prop = {};
  // above with
  //     meta.prop = vm.runInContext('{}', contextifiedObject);
})();

sourceTextModule.createCachedData()

• Возвращает: <Buffer>

Создает кэш кода, который можно использовать с параметром cachedData конструктора SourceTextModule. Возвращает Buffer. Этот метод можно вызвать любое количество раз до вычисления модуля.

Кэш кода SourceTextModule не содержит состояний, наблюдаемых из JavaScript. Кэш кода можно безопасно сохранять вместе с исходным текстом скрипта и многократно использовать для создания новых экземпляров SourceTextModule.

Функции в исходном коде SourceTextModule могут быть помечены для отложенной компиляции; в таком случае они не компилируются при создании SourceTextModule. Эти функции будут скомпилированы при первом вызове. Кэш кода сериализует метаданные, известные V8 на данный момент о SourceTextModule, которые могут ускорить последующие компиляции.

// Create an initial module
const module = new vm.SourceTextModule('const a = 1;');

// Create cached data from this module
const cachedData = module.createCachedData();

// Create a new module using the cached data. The code must be the same.
const module2 = new vm.SourceTextModule('const a = 1;', { cachedData }); copy

sourceTextModule.dependencySpecifiers

• Тип: <string[]>

Спецификаторы всех зависимостей этого модуля. Возвращаемый массив заморожен, чтобы запретить его изменение.

Соответствует полю [[RequestedModules]] циклических записей модулей в спецификации ECMAScript.

sourceTextModule.hasAsyncGraph()

• Возвращает: <boolean>

Обходит граф зависимостей и возвращает true, если в зависимостях или самом модуле есть выражения верхнего уровня await; в противном случае возвращает false.

При достаточно большом графе поиск может выполняться медленно.

Для этого модуль сначала должен быть инстанцирован. Если модуль еще не инстанцирован, будет выброшена ошибка.

sourceTextModule.hasTopLevelAwait()

• Возвращает: <boolean>

Возвращает значение, указывающее, содержит ли сам модуль какие-либо выражения верхнего уровня await.

Соответствует полю [[HasTLA]] в циклической записи модуля в спецификации ECMAScript.

sourceTextModule.instantiate()

• Возвращает: <undefined>

Инстанцирует модуль со связанными запрошенными модулями.

Разрешает импортированные привязки модуля, включая имена повторно экспортируемых привязок. Если есть привязки, которые невозможно разрешить, синхронно будет выброшена ошибка.

Если среди запрошенных модулей есть циклические зависимости, метод sourceTextModule.linkRequests(modules) необходимо вызвать для всех модулей цикла до вызова этого метода.

sourceTextModule.linkRequests(modules)

• modules <vm.Module[]> Массив объектов vm.Module, от которых зависит этот модуль. Порядок модулей в массиве соответствует порядку sourceTextModule.moduleRequests.
• Возвращает: <undefined>

Связывает зависимости модуля. Этот метод необходимо вызвать до вычисления; его можно вызвать только один раз для каждого модуля.

Порядок экземпляров модулей в массиве modules должен соответствовать порядку разрешения sourceTextModule.moduleRequests. Если два запроса модуля имеют одинаковые спецификатор и атрибуты импорта, для них должен быть разрешен один и тот же экземпляр модуля, иначе будет выброшен ERR_MODULE_LINK_MISMATCH. Например, при связывании запросов для этого модуля:

import foo from 'foo';
import source Foo from 'foo'; copy

Массив modules должен содержать две ссылки на один и тот же экземпляр, поскольку два запроса модуля идентичны, но относятся к двум фазам.

Если у модуля нет зависимостей, массив modules может быть пустым.

Пользователи могут использовать sourceTextModule.moduleRequests для реализации определенной средой выполнения абстрактной операции HostLoadImportedModule в спецификации ECMAScript и использовать sourceTextModule.linkRequests() для вызова определенной спецификацией операции FinishLoadingImportedModule для модуля со всеми зависимостями в одном пакете.

Создатель SourceTextModule сам определяет, будет ли разрешение зависимостей синхронным или асинхронным.

После связывания каждого модуля в массиве modules вызовите sourceTextModule.instantiate().

sourceTextModule.moduleRequests

• Тип: <ModuleRequest[]> Зависимости этого модуля.

Запрошенные зависимости импорта этого модуля. Возвращаемый массив заморожен, чтобы запретить его изменение.

Например, для следующего исходного текста:

import foo from 'foo';
import fooAlias from 'foo';
import bar from './bar.js';
import withAttrs from '../with-attrs.ts' with { arbitraryAttr: 'attr-val' };
import source Module from 'wasm-mod.wasm'; copy

Значение sourceTextModule.moduleRequests будет следующим:

[
  {
    specifier: 'foo',
    attributes: {},
    phase: 'evaluation',
  },
  {
    specifier: 'foo',
    attributes: {},
    phase: 'evaluation',
  },
  {
    specifier: './bar.js',
    attributes: {},
    phase: 'evaluation',
  },
  {
    specifier: '../with-attrs.ts',
    attributes: { arbitraryAttr: 'attr-val' },
    phase: 'evaluation',
  },
  {
    specifier: 'wasm-mod.wasm',
    attributes: {},
    phase: 'source',
  },
]; copy

new vm.SyntheticModule(exportNames, evaluateCallback[, options])

• exportNames <string[]> Массив имен, которые будут экспортироваться из модуля.
• evaluateCallback <Function> Вызывается при вычислении модуля.
• options
  • identifier <string> Строка, используемая в трассировках стека. По умолчанию: 'vm:module(i)', где i — возрастающий индекс, зависящий от контекста.
  • context <Object> Объект, преобразованный в контекст, как возвращаемый методом vm.createContext(), в котором следует скомпилировать и вычислить этот Module.

Создает новый экземпляр SyntheticModule.

Объекты, присвоенные экспортам этого экземпляра, могут позволить импортирующим модулям получить доступ к информации за пределами указанного context. Используйте vm.runInContext(), чтобы создавать объекты в определенном контексте.

syntheticModule.setExport(name, value)

• name <string> Имя экспорта, которому нужно присвоить значение.
• value <any> Значение, присваиваемое экспорту.

Этот метод задает значения слотов привязок экспорта модуля.

import vm from 'node:vm';

const m = new vm.SyntheticModule(['x'], () => {
  m.setExport('x', 1);
});

await m.evaluate();

assert.strictEqual(m.namespace.x, 1);

const vm = require('node:vm');
(async () => {
  const m = new vm.SyntheticModule(['x'], () => {
    m.setExport('x', 1);
  });
  await m.evaluate();
  assert.strictEqual(m.namespace.x, 1);
})();

vm.constants.USE_MAIN_CONTEXT_DEFAULT_LOADER

Константа, которую можно использовать в качестве параметра importModuleDynamically для vm.Script и vm.compileFunction(), чтобы Node.js использовал загрузчик ESM по умолчанию из основного контекста для загрузки запрошенного модуля.

Подробные сведения см. в разделе Поддержка динамического import() в API компиляции.

vm.constants.DONT_CONTEXTIFY

Эта константа, используемая в качестве аргумента contextObject в API vm, указывает Node.js создать контекст, не оборачивая его глобальный объект другим объектом способом, специфичным для Node.js. В результате значение globalThis в новом контексте будет вести себя ближе к обычному.

const vm = require('node:vm');

// Use vm.constants.DONT_CONTEXTIFY to freeze the global object.
const context = vm.createContext(vm.constants.DONT_CONTEXTIFY);
vm.runInContext('Object.freeze(globalThis);', context);
try {
  vm.runInContext('bar = 1; bar;', context);
} catch (e) {
  console.log(e); // Uncaught ReferenceError: bar is not defined
} copy

Если vm.constants.DONT_CONTEXTIFY используется в качестве аргумента contextObject для vm.createContext(), возвращаемый объект будет подобным прокси объектом глобального объекта в новом контексте с меньшим количеством особенностей, специфичных для Node.js. Он будет ссылочно равен значению globalThis в новом контексте, его можно будет изменять извне контекста и использовать для прямого доступа к встроенным объектам нового контекста.

const vm = require('node:vm');

const context = vm.createContext(vm.constants.DONT_CONTEXTIFY);

// Returned object is reference equal to globalThis in the new context.
console.log(vm.runInContext('globalThis', context) === context);  // true

// Can be used to access globals in the new context directly.
console.log(context.Array);  // [Function: Array]
vm.runInContext('foo = 1;', context);
console.log(context.foo);  // 1
context.bar = 1;
console.log(vm.runInContext('bar;', context));  // 1

// Can be frozen and it affects the inner context.
Object.freeze(context);
try {
  vm.runInContext('baz = 1; baz;', context);
} catch (e) {
  console.log(e); // Uncaught ReferenceError: baz is not defined
} copy

Если microtaskMode имеет значение 'afterEvaluate', будьте осторожны при совместном использовании промисов между контекстами

В режиме 'afterEvaluate' у Context есть собственная очередь микрозадач, отдельная от глобальной очереди микрозадач внешнего (основного) контекста. Хотя этот режим необходим для обеспечения timeout и поддержки breakOnSigint с асинхронными задачами, он также усложняет совместное использование промисов между контекстами.

В приведенном ниже примере промис создается во внутреннем контексте и передается во внешний. Когда внешний контекст вызывает await для этого промиса, поток выполнения внешнего контекста неожиданным образом нарушается: оператор log никогда не выполняется.

import * as vm from 'node:vm';

const inner_context = vm.createContext({}, { microtaskMode: 'afterEvaluate' });

// runInContext() returns a Promise created in the inner context.
const inner_promise = vm.runInContext(
  'Promise.resolve()',
  context,
);

// As part of performing `await`, the JavaScript runtime must enqueue a task
// on the microtask queue of the context where `inner_promise` was created.
// A task is added on the inner microtask queue, but **it will not be run
// automatically**: this task will remain pending indefinitely.
//
// Since the outer microtask queue is empty, execution in the outer module
// falls through, and the log statement below is never executed.
await inner_promise;

console.log('this will NOT be printed'); copy

Чтобы успешно использовать промисы совместно между контекстами с разными очередями микрозадач, необходимо обеспечить выполнение задач во внутренней очереди микрозадач каждый раз, когда внешний контекст помещает задачу во внутреннюю очередь микрозадач.

Задачи в очереди микрозадач заданного контекста выполняются при каждом вызове runInContext() или SourceTextModule.evaluate() для скрипта или модуля, использующего этот контекст. В нашем примере обычный поток выполнения можно восстановить, запланировав второй вызов runInContext() до await inner_promise.

// Schedule `runInContext()` to manually drain the inner context microtask
// queue; it will run after the `await` statement below.
setImmediate(() => {
  vm.runInContext('', context);
});

await inner_promise;

console.log('OK'); copy

Примечание: Строго говоря, в этом режиме node:vm отступает от буквального текста спецификации ECMAScript для постановки заданий в очередь, позволяя асинхронным задачам из разных контекстов выполняться в порядке, отличном от порядка их постановки в очередь.

Если параметр importModuleDynamically не указан или имеет значение undefined

Если этот параметр не указан или имеет значение undefined, код, содержащий import(), все равно можно скомпилировать с помощью API vm, однако при выполнении скомпилированного кода и фактическом вызове import() результат будет отклонен с ошибкой ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING.

Если importModuleDynamically имеет значение vm.constants.USE_MAIN_CONTEXT_DEFAULT_LOADER

В настоящее время этот параметр не поддерживается для vm.SourceTextModule.

При использовании этого параметра, если в скомпилированном коде запускается import(), Node.js использует загрузчик ESM по умолчанию из основного контекста для загрузки запрошенного модуля и передает его выполняемому коду.

Это предоставляет компилируемому коду доступ к встроенным модулям Node.js, таким как fs или http. Если код выполняется в другом контексте, обратите внимание, что объекты, созданные модулями, загруженными из основного контекста, по-прежнему относятся к основному контексту, а не к встроенным классам instanceof в новом контексте.

const { Script, constants } = require('node:vm');
const script = new Script(
  'import("node:fs").then(({readFile}) => readFile instanceof Function)',
  { importModuleDynamically: constants.USE_MAIN_CONTEXT_DEFAULT_LOADER });

// false: URL loaded from the main context is not an instance of the Function
// class in the new context.
script.runInNewContext().then(console.log);

import { Script, constants } from 'node:vm';

const script = new Script(
  'import("node:fs").then(({readFile}) => readFile instanceof Function)',
  { importModuleDynamically: constants.USE_MAIN_CONTEXT_DEFAULT_LOADER });

// false: URL loaded from the main context is not an instance of the Function
// class in the new context.
script.runInNewContext().then(console.log);

Этот параметр также позволяет скрипту или функции загружать пользовательские модули:

import { Script, constants } from 'node:vm';
import { resolve } from 'node:path';
import { writeFileSync } from 'node:fs';

// Write test.js and test.txt to the directory where the current script
// being run is located.
writeFileSync(resolve(import.meta.dirname, 'test.mjs'),
              'export const filename = "./test.json";');
writeFileSync(resolve(import.meta.dirname, 'test.json'),
              '{"hello": "world"}');

// Compile a script that loads test.mjs and then test.json
// as if the script is placed in the same directory.
const script = new Script(
  `(async function() {
    const { filename } = await import('./test.mjs');
    return import(filename, { with: { type: 'json' } })
  })();`,
  {
    filename: resolve(import.meta.dirname, 'test-with-default.js'),
    importModuleDynamically: constants.USE_MAIN_CONTEXT_DEFAULT_LOADER,
  });

// { default: { hello: 'world' } }
script.runInThisContext().then(console.log);

const { Script, constants } = require('node:vm');
const { resolve } = require('node:path');
const { writeFileSync } = require('node:fs');

// Write test.js and test.txt to the directory where the current script
// being run is located.
writeFileSync(resolve(__dirname, 'test.mjs'),
              'export const filename = "./test.json";');
writeFileSync(resolve(__dirname, 'test.json'),
              '{"hello": "world"}');

// Compile a script that loads test.mjs and then test.json
// as if the script is placed in the same directory.
const script = new Script(
  `(async function() {
    const { filename } = await import('./test.mjs');
    return import(filename, { with: { type: 'json' } })
  })();`,
  {
    filename: resolve(__dirname, 'test-with-default.js'),
    importModuleDynamically: constants.USE_MAIN_CONTEXT_DEFAULT_LOADER,
  });

// { default: { hello: 'world' } }
script.runInThisContext().then(console.log);

При загрузке пользовательских модулей с помощью загрузчика по умолчанию из основного контекста есть несколько особенностей:

1. Разрешаемый модуль будет искать путь относительно параметра filename, переданного в vm.Script или vm.compileFunction(). Разрешение пути может работать с filename, заданным в виде абсолютного пути или строки URL. Если filename — строка, которая не является ни абсолютным путем, ни URL, либо если он не определен, поиск будет выполняться относительно текущего рабочего каталога процесса. В случае vm.createContext() поиск всегда выполняется относительно текущего рабочего каталога, поскольку этот параметр используется только при отсутствии скрипта или модуля-источника.
2. Для любого filename, разрешающегося в определенный путь, после загрузки процессом конкретного модуля из этого пути результат может быть кэширован, и последующие загрузки того же модуля из того же пути будут возвращать тот же объект. Если filename — строка URL, запись кэша не будет найдена, если параметры запроса отличаются. Для filename, не являющихся строками URL, в настоящее время нет способа обойти кэширование.

Если importModuleDynamically является функцией

Если importModuleDynamically является функцией, она будет вызвана при вызове import() в скомпилированном коде, чтобы пользователи могли настроить способ компиляции и вычисления запрошенного модуля. В настоящее время для работы этого параметра экземпляр Node.js необходимо запускать с флагом --experimental-vm-modules. Если флаг не задан, этот обратный вызов будет проигнорирован. Если вычисляемый код действительно вызывает import(), результат будет отклонен с ошибкой ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING_FLAG.

Обратный вызов importModuleDynamically(specifier, referrer, importAttributes) имеет следующую сигнатуру:

• specifier <string> спецификатор, переданный в import()
• referrer <vm.Script> | <Function> | <vm.SourceTextModule> | <Object> Источник — это скомпилированный vm.Script для new vm.Script, vm.runInThisContext, vm.runInContext и vm.runInNewContext. Для vm.compileFunction это скомпилированный Function, для new vm.SourceTextModule — скомпилированный vm.SourceTextModule, а для vm.createContext() — контекст Object.
• importAttributes <Object> Значение "with", переданное в необязательный параметр optionsExpression, или пустой объект, если значение не было предоставлено.
• phase <string> Фаза динамического импорта ("source" или "evaluation").
• Возвращает: <Module Namespace Object> | <vm.Module> Рекомендуется возвращать vm.Module, чтобы воспользоваться отслеживанием ошибок и избежать проблем с пространствами имен, содержащими экспорты функций then.

// This script must be run with --experimental-vm-modules.
import { Script, SyntheticModule } from 'node:vm';

const script = new Script('import("foo.json", { with: { type: "json" } })', {
  async importModuleDynamically(specifier, referrer, importAttributes) {
    console.log(specifier);  // 'foo.json'
    console.log(referrer);   // The compiled script
    console.log(importAttributes);  // { type: 'json' }
    const m = new SyntheticModule(['bar'], () => { });
    await m.link(() => { });
    m.setExport('bar', { hello: 'world' });
    return m;
  },
});
const result = await script.runInThisContext();
console.log(result);  //  { bar: { hello: 'world' } }

// This script must be run with --experimental-vm-modules.
const { Script, SyntheticModule } = require('node:vm');

(async function main() {
  const script = new Script('import("foo.json", { with: { type: "json" } })', {
    async importModuleDynamically(specifier, referrer, importAttributes) {
      console.log(specifier);  // 'foo.json'
      console.log(referrer);   // The compiled script
      console.log(importAttributes);  // { type: 'json' }
      const m = new SyntheticModule(['bar'], () => { });
      await m.link(() => { });
      m.setExport('bar', { hello: 'world' });
      return m;
    },
  });
  const result = await script.runInThisContext();
  console.log(result);  //  { bar: { hello: 'world' } }
})();