Кэш компиляции модулей

Кэш компиляции модулей можно включить с помощью метода module.enableCompileCache() или переменной окружения NODE_COMPILE_CACHE=dir. После включения кэша при компиляции Node.js модулей CommonJS или ECMAScript будет использовать сохранённый на диске кэш кода V8 из указанного каталога, чтобы ускорить компиляцию. Это может замедлить первую загрузку графа модулей, но последующие загрузки того же графа могут выполняться значительно быстрее, если содержимое модулей не изменилось.

Чтобы очистить созданный на диске кэш компиляции, достаточно удалить каталог кэша. При следующем использовании того же каталога для хранения кэша компиляции он будет создан заново. Чтобы не заполнять диск устаревшими данными кэша, рекомендуется использовать каталог внутри os.tmpdir(). Если кэш компиляции включён вызовом module.enableCompileCache() без указания каталога, Node.js использует переменную окружения NODE_COMPILE_CACHE=dir, если она задана, либо path.join(os.tmpdir(), 'node-compile-cache') по умолчанию. Чтобы узнать каталог кэша компиляции, используемый работающим экземпляром Node.js, вызовите module.getCompileCacheDir().

При использовании кэша компиляции вместе с покрытием кода JavaScript V8 данные о покрытии, собираемые V8, могут быть менее точными для функций, десериализованных из кэша кода. Для получения точных данных о покрытии рекомендуется отключать кэш при запуске тестов.

Включённый кэш компиляции модулей можно отключить с помощью переменной окружения NODE_DISABLE_COMPILE_CACHE=1. Это может быть полезно, если кэш компиляции приводит к неожиданному или нежелательному поведению (например, к снижению точности покрытия кода в тестах).

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

В настоящее время при включённом кэше компиляции и первой загрузке модуля кэш кода создаётся сразу после компиляции, но записывается на диск только перед завершением работы экземпляра Node.js. Это поведение может измениться. Метод module.flushCompileCache() позволяет принудительно записать накопленный кэш кода на диск, если приложение собирается запустить другие экземпляры Node.js и предоставить им доступ к кэшу задолго до завершения работы родительского экземпляра.

Асинхронные хуки, принимаемые module.register()

Метод register можно использовать для регистрации модуля, экспортирующего набор хуков. Хуки — это функции, вызываемые Node.js для настройки процесса разрешения и загрузки модулей. Экспортируемые функции должны иметь определённые имена и сигнатуры, а также экспортироваться как именованные экспорты.

export async function initialize({ number, port }) {
  // Receives data from `register`.
}

export async function resolve(specifier, context, nextResolve) {
  // Take an `import` or `require` specifier and resolve it to a URL.
}

export async function load(url, context, nextLoad) {
  // Take a resolved URL and return the source code to be evaluated.
} copy

Асинхронные хуки выполняются в отдельном потоке, изолированном от основного потока, в котором работает код приложения. Это означает, что они находятся в другой среде. Основной поток может в любой момент завершить поток хуков, поэтому не полагайтесь на завершение асинхронных операций (например, console.log). По умолчанию они наследуются дочерними рабочими потоками.

Синхронные хуки, принимаемые module.registerHooks()

Метод module.registerHooks() принимает функции синхронных хуков. initialize() не поддерживается и не требуется, поскольку реализующий хук может просто выполнить код инициализации непосредственно перед вызовом module.registerHooks().

function resolve(specifier, context, nextResolve) {
  // Take an `import` or `require` specifier and resolve it to a URL.
}

function load(url, context, nextLoad) {
  // Take a resolved URL and return the source code to be evaluated.
} copy

Синхронные хуки выполняются в том же потоке и той же среде, в которых загружаются модули. В отличие от асинхронных хуков, по умолчанию они не наследуются дочерними рабочими потоками. Однако, если хуки зарегистрированы с помощью файла, предварительно загруженного через --import или --require, дочерние рабочие потоки могут наследовать предварительно загруженные скрипты посредством наследования process.execArgv. Подробности см. в документации по Worker.

При использовании синхронных хуков можно ожидать, что console.log() завершится так же, как ожидается завершение console.log() в коде модуля.

Соглашения об использовании хуков

Хуки являются частью цепочки, даже если она состоит только из одного пользовательского (предоставленного пользователем) хука и стандартного хука, который присутствует всегда. Функции хуков образуют вложенную структуру: каждая из них всегда должна возвращать обычный объект, а цепочка формируется в результате вызова каждой функцией next<hookName>() — ссылки на хук следующего загрузчика (в порядке LIFO).

Если хук возвращает значение, в котором отсутствует обязательное свойство, возникает исключение. Если хук возвращает значение, не вызывая next<hookName>() и не возвращая shortCircuit: true, также возникает исключение. Эти ошибки помогают предотвратить непреднамеренные нарушения цепочки. Возвращайте из хука shortCircuit: true, чтобы указать, что цепочка намеренно завершается на вашем хуке.

initialize()

• data <any> Данные из register(loader, import.meta.url, { data }).

Хук initialize принимается только методом register. registerHooks() не поддерживает его и не нуждается в нём, поскольку инициализацию синхронных хуков можно выполнить непосредственно перед вызовом registerHooks().

Хук initialize позволяет определить пользовательскую функцию, которая запускается в потоке хуков при инициализации модуля хуков. Инициализация выполняется при регистрации модуля хуков с помощью register.

Этот хук может получать данные из вызова register, в том числе порты и другие передаваемые объекты. Возвращаемым значением initialize может быть <Promise>; в таком случае его результат будет ожидаться до возобновления выполнения в основном потоке приложения.

Код настройки модулей:

// path-to-my-hooks.js

export async function initialize({ number, port }) {
  port.postMessage(`increment: ${number + 1}`);
} copy

Код вызывающего модуля:

import assert from 'node:assert';
import { register } from 'node:module';
import { MessageChannel } from 'node:worker_threads';

// This example showcases how a message channel can be used to communicate
// between the main (application) thread and the hooks running on the hooks
// thread, by sending `port2` to the `initialize` hook.
const { port1, port2 } = new MessageChannel();

port1.on('message', (msg) => {
  assert.strictEqual(msg, 'increment: 2');
});
port1.unref();

register('./path-to-my-hooks.js', {
  parentURL: import.meta.url,
  data: { number: 1, port: port2 },
  transferList: [port2],
});

const assert = require('node:assert');
const { register } = require('node:module');
const { pathToFileURL } = require('node:url');
const { MessageChannel } = require('node:worker_threads');

// This example showcases how a message channel can be used to communicate
// between the main (application) thread and the hooks running on the hooks
// thread, by sending `port2` to the `initialize` hook.
const { port1, port2 } = new MessageChannel();

port1.on('message', (msg) => {
  assert.strictEqual(msg, 'increment: 2');
});
port1.unref();

register('./path-to-my-hooks.js', {
  parentURL: pathToFileURL(__filename),
  data: { number: 1, port: port2 },
  transferList: [port2],
});

resolve(specifier, context, nextResolve)

• specifier <string>
• context <Object>
  • conditions <string[]> Условия экспорта для соответствующего package.json
  • importAttributes <Object> Объект, пары ключ-значение которого представляют атрибуты импортируемого модуля
  • parentURL <string> | <undefined> Модуль, импортирующий этот модуль, или undefined, если это точка входа Node.js
• nextResolve <Function> Следующий хук resolve в цепочке или стандартный хук resolve Node.js после последнего предоставленного пользователем хука resolve
  • specifier <string>
  • context <Object> | <undefined> Если свойство не указано, используются значения по умолчанию. Если свойство указано, значения по умолчанию объединяются с ним, при этом предпочтение отдаётся указанным свойствам.
• Возвращает: <Object> | <Promise> Асинхронная версия принимает объект со следующими свойствами либо Promise, результатом которого станет такой объект. Синхронная версия принимает только объект, возвращённый синхронно.
  • format <string> | <null> | <undefined> Подсказка для хука load (она может быть проигнорирована). Это может быть формат модуля (например, 'commonjs' или 'module') либо произвольное значение, например 'css' или 'yaml'.
  • importAttributes <Object> | <undefined> Атрибуты импорта, используемые при кэшировании модуля (необязательно; если они не указаны, будут использованы входные данные)
  • shortCircuit <undefined> | <boolean> Указывает, что этот хук намерен завершить цепочку хуков resolve. По умолчанию: false
  • url <string> Абсолютный URL, в который разрешается этот входной параметр

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

Цепочка хуков resolve отвечает за указание Node.js, где найти и как кэшировать заданную инструкцию или выражение import либо вызов require. При необходимости она может возвращать формат (например, 'module') в качестве подсказки для хука load. Если формат указан, хук load в конечном счёте отвечает за предоставление итогового значения format (и может проигнорировать подсказку, предоставленную resolve); если resolve предоставляет format, требуется пользовательский хук load, даже если он лишь передаёт значение стандартному хуку load Node.js.

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

Свойство conditions в context — это массив условий, используемых для сопоставления условий экспорта пакета для этого запроса разрешения. Их можно использовать для поиска условных сопоставлений в других местах или для изменения списка при вызове логики разрешения по умолчанию.

Текущие условия экспорта пакета всегда находятся в массиве context.conditions, передаваемом хуку. Чтобы при вызове defaultResolve гарантировать поведение разрешения спецификаторов модулей Node.js по умолчанию, массив context.conditions, передаваемый ему, должен включать все элементы массива context.conditions, изначально переданного хуку resolve.

// Asynchronous version accepted by module.register().
export async function resolve(specifier, context, nextResolve) {
  const { parentURL = null } = context;

  if (Math.random() > 0.5) { // Some condition.
    // For some or all specifiers, do some custom logic for resolving.
    // Always return an object of the form {url: <string>}.
    return {
      shortCircuit: true,
      url: parentURL ?
        new URL(specifier, parentURL).href :
        new URL(specifier).href,
    };
  }

  if (Math.random() < 0.5) { // Another condition.
    // When calling `defaultResolve`, the arguments can be modified. In this
    // case it's adding another value for matching conditional exports.
    return nextResolve(specifier, {
      ...context,
      conditions: [...context.conditions, 'another-condition'],
    });
  }

  // Defer to the next hook in the chain, which would be the
  // Node.js default resolve if this is the last user-specified loader.
  return nextResolve(specifier);
} copy

// Synchronous version accepted by module.registerHooks().
function resolve(specifier, context, nextResolve) {
  // Similar to the asynchronous resolve() above, since that one does not have
  // any asynchronous logic.
} copy

load(url, context, nextLoad)

• url <string> URL, возвращённый цепочкой resolve
• context <Object>
  • conditions <string[]> Условия экспорта соответствующего package.json
  • format <string> | <null> | <undefined> Формат, необязательно предоставленный цепочкой хуков resolve. В качестве входных данных может использоваться любое строковое значение; входные значения не обязаны соответствовать списку допустимых возвращаемых значений, описанному ниже.
  • importAttributes <Object>
• nextLoad <Function> Следующий хук load в цепочке или стандартный хук load Node.js после последнего заданного пользователем хука load
  • url <string>
  • context <Object> | <undefined> Если параметр не указан, используются значения по умолчанию. Если он указан, значения по умолчанию объединяются с ним, причём приоритет имеют заданные свойства. В стандартном nextLoad, если модуль, на который указывает url, не содержит явных сведений о типе модуля, параметр context.format обязателен.
• Возвращает: <Object> | <Promise> Асинхронная версия принимает либо объект со следующими свойствами, либо Promise, который разрешится в такой объект. Синхронная версия принимает только объект, возвращённый синхронно.
  • format <string>
  • shortCircuit <undefined> | <boolean> Сигнал о том, что этот хук намерен завершить цепочку хуков load. По умолчанию: false
  • source <string> | <ArrayBuffer> | <TypedArray> Исходный код, который должен выполнить Node.js

Хук load позволяет определить пользовательский способ интерпретации, получения и разбора URL. Он также отвечает за проверку атрибутов импорта.

Итоговое значение format должно быть одним из следующих:

Значение source игнорируется для типа 'builtin', поскольку в настоящее время заменить значение встроенного (основного) модуля Node.js невозможно.

import { readFile } from 'node:fs/promises';

// Asynchronous version accepted by module.register(). This fix is not needed
// for the synchronous version accepted by module.registerHooks().
export async function load(url, context, nextLoad) {
  const result = await nextLoad(url, context);
  if (result.format === 'commonjs') {
    result.source ??= await readFile(new URL(result.responseURL ?? url));
  }
  return result;
} copy

// Asynchronous version accepted by module.register().
export async function load(url, context, nextLoad) {
  const { format } = context;

  if (Math.random() > 0.5) { // Some condition
    /*
      For some or all URLs, do some custom logic for retrieving the source.
      Always return an object of the form {
        format: <string>,
        source: <string|buffer>,
      }.
    */
    return {
      format,
      shortCircuit: true,
      source: '...',
    };
  }

  // Defer to the next hook in the chain.
  return nextLoad(url);
} copy

// Synchronous version accepted by module.registerHooks().
function load(url, context, nextLoad) {
  // Similar to the asynchronous load() above, since that one does not have
  // any asynchronous logic.
} copy

Импорт по HTTPS

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

// https-hooks.mjs
import { get } from 'node:https';

export function load(url, context, nextLoad) {
  // For JavaScript to be loaded over the network, we need to fetch and
  // return it.
  if (url.startsWith('https://')) {
    return new Promise((resolve, reject) => {
      get(url, (res) => {
        let data = '';
        res.setEncoding('utf8');
        res.on('data', (chunk) => data += chunk);
        res.on('end', () => resolve({
          // This example assumes all network-provided JavaScript is ES module
          // code.
          format: 'module',
          shortCircuit: true,
          source: data,
        }));
      }).on('error', (err) => reject(err));
    });
  }

  // Let Node.js handle all other URLs.
  return nextLoad(url);
} copy

// main.mjs
import { VERSION } from 'https://coffeescript.org/browser-compiler-modern/coffeescript.js';

console.log(VERSION); copy

При использовании описанного выше модуля хуков запуск node --import 'data:text/javascript,import { register } from "node:module"; import { pathToFileURL } from "node:url"; register(pathToFileURL("./https-hooks.mjs"));' ./main.mjs выводит текущую версию CoffeeScript согласно модулю по URL в main.mjs.

Транспиляция

Исходный код в форматах, которые Node.js не понимает, можно преобразовать в JavaScript с помощью хука load.

Это менее производительно, чем транспиляция исходных файлов до запуска Node.js; хуки транспилятора следует использовать только для разработки и тестирования.

// coffeescript-hooks.mjs
import { readFile } from 'node:fs/promises';
import { findPackageJSON } from 'node:module';
import coffeescript from 'coffeescript';

const extensionsRegex = /\.(coffee|litcoffee|coffee\.md)$/;

export async function load(url, context, nextLoad) {
  if (extensionsRegex.test(url)) {
    // CoffeeScript files can be either CommonJS or ES modules. Use a custom format
    // to tell Node.js not to detect its module type.
    const { source: rawSource } = await nextLoad(url, { ...context, format: 'coffee' });
    // This hook converts CoffeeScript source code into JavaScript source code
    // for all imported CoffeeScript files.
    const transformedSource = coffeescript.compile(rawSource.toString(), url);

    // To determine how Node.js would interpret the transpilation result,
    // search up the file system for the nearest parent package.json file
    // and read its "type" field.
    return {
      format: await getPackageType(url),
      shortCircuit: true,
      source: transformedSource,
    };
  }

  // Let Node.js handle all other URLs.
  return nextLoad(url, context);
}

async function getPackageType(url) {
  // `url` is only a file path during the first iteration when passed the
  // resolved url from the load() hook
  // an actual file path from load() will contain a file extension as it's
  // required by the spec
  // this simple truthy check for whether `url` contains a file extension will
  // work for most projects but does not cover some edge-cases (such as
  // extensionless files or a url ending in a trailing space)
  const pJson = findPackageJSON(url);

  return readFile(pJson, 'utf8')
    .then(JSON.parse)
    .then((json) => json?.type)
    .catch(() => undefined);
} copy

// coffeescript-sync-hooks.mjs
import { readFileSync } from 'node:fs';
import { registerHooks, findPackageJSON } from 'node:module';
import coffeescript from 'coffeescript';

const extensionsRegex = /\.(coffee|litcoffee|coffee\.md)$/;

function load(url, context, nextLoad) {
  if (extensionsRegex.test(url)) {
    const { source: rawSource } = nextLoad(url, { ...context, format: 'coffee' });
    const transformedSource = coffeescript.compile(rawSource.toString(), url);

    return {
      format: getPackageType(url),
      shortCircuit: true,
      source: transformedSource,
    };
  }

  return nextLoad(url, context);
}

function getPackageType(url) {
  const pJson = findPackageJSON(url);
  if (!pJson) {
    return undefined;
  }
  try {
    const file = readFileSync(pJson, 'utf-8');
    return JSON.parse(file)?.type;
  } catch {
    return undefined;
  }
}

registerHooks({ load }); copy

Запуск хуков

# main.coffee
import { scream } from './scream.coffee'
console.log scream 'hello, world'

import { version } from 'node:process'
console.log "Brought to you by Node.js version #{version}" copy

# scream.coffee
export scream = (str) -> str.toUpperCase() copy

Чтобы запустить пример, добавьте файл package.json, содержащий тип модуля для файлов CoffeeScript.

{
  "type": "module"
} copy

Это требуется только для запуска примера. В реальных загрузчиках getPackageType() должен возвращать format, известный Node.js, даже если в package.json явно не указан тип, иначе вызов nextLoad вызовет ошибку ERR_UNKNOWN_FILE_EXTENSION (если значение не определено) или ERR_UNKNOWN_MODULE_FORMAT (если формат не входит в список известных форматов, приведённый в документации по хуку загрузки).

При использовании описанных выше модулей хуков запуск node --import 'data:text/javascript,import { register } from "node:module"; import { pathToFileURL } from "node:url"; register(pathToFileURL("./coffeescript-hooks.mjs"));' ./main.coffee или node --import ./coffeescript-sync-hooks.mjs ./main.coffee приводит к преобразованию main.coffee в JavaScript после загрузки его исходного кода с диска, но до его выполнения Node.js; то же самое происходит с любыми файлами .coffee, .litcoffee или .coffee.md, на которые ссылаются инструкции import в любом загруженном файле.

Карты импорта

В двух предыдущих примерах были определены хуки load. В этом примере показан хук resolve. Этот модуль хуков читает файл import-map.json, в котором задаётся, какие спецификаторы нужно перенаправить на другие URL (это очень упрощённая реализация небольшой части спецификации «карт импорта»).

// import-map-hooks.js
import fs from 'node:fs/promises';

const { imports } = JSON.parse(await fs.readFile('import-map.json'));

export async function resolve(specifier, context, nextResolve) {
  if (Object.hasOwn(imports, specifier)) {
    return nextResolve(imports[specifier], context);
  }

  return nextResolve(specifier, context);
} copy

// import-map-sync-hooks.js
import fs from 'node:fs/promises';
import module from 'node:module';

const { imports } = JSON.parse(fs.readFileSync('import-map.json', 'utf-8'));

function resolve(specifier, context, nextResolve) {
  if (Object.hasOwn(imports, specifier)) {
    return nextResolve(imports[specifier], context);
  }

  return nextResolve(specifier, context);
}

module.registerHooks({ resolve }); copy

// main.js
import 'a-module'; copy

// import-map.json
{
  "imports": {
    "a-module": "./some-module.js"
  }
} copy

// some-module.js
console.log('some module!'); copy

new SourceMap(payload[, { lineLengths }])

• payload <Object>
• lineLengths <number[]>

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

payload — это объект с ключами, соответствующими формату карт исходного кода:

• file <string>
• version <number>
• sources <string[]>
• sourcesContent <string[]>
• names <string[]>
• mappings <string>
• sourceRoot <string>

lineLengths — это необязательный массив, содержащий длину каждой строки сгенерированного кода.

sourceMap.payload

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

Геттер для данных, использованных при создании экземпляра SourceMap.

sourceMap.findEntry(lineOffset, columnOffset)

• lineOffset <number> Смещение номера строки в сгенерированном исходном коде с отсчётом от нуля
• columnOffset <number> Смещение номера столбца в сгенерированном исходном коде с отсчётом от нуля
• Возвращает: <Object>

Принимая смещения строки и столбца в файле сгенерированного исходного кода, возвращает объект, представляющий диапазон SourceMap в исходном файле, если он найден, или пустой объект, если нет.

Возвращаемый объект содержит следующие ключи:

• generatedLine <number> Смещение строки начала диапазона в сгенерированном исходном коде
• generatedColumn <number> Смещение столбца начала диапазона в сгенерированном исходном коде
• originalSource <string> Имя файла исходного кода, указанное в SourceMap
• originalLine <number> Смещение строки начала диапазона в исходном коде
• originalColumn <number> Смещение столбца начала диапазона в исходном коде
• name <string>

Возвращаемое значение представляет исходный диапазон в том виде, в каком он указан в SourceMap, с использованием смещений с отсчётом от нуля, а не номеров строк и столбцов с отсчётом от единицы, которые используются в сообщениях Error и объектах CallSite.

Чтобы получить соответствующие номера строк и столбцов с отсчётом от единицы из lineNumber и columnNumber, указанных в стеках Error и объектах CallSite, используйте sourceMap.findOrigin(lineNumber, columnNumber)

sourceMap.findOrigin(lineNumber, columnNumber)

• lineNumber <number> Номер строки места вызова в сгенерированном исходном коде с отсчётом от единицы
• columnNumber <number> Номер столбца места вызова в сгенерированном исходном коде с отсчётом от единицы
• Возвращает: <Object>

По lineNumber и columnNumber с отсчётом от единицы для места вызова в сгенерированном исходном коде находит соответствующее место вызова в исходном коде.

Если указанные lineNumber и columnNumber не найдены ни в одной карте исходного кода, возвращается пустой объект. В противном случае возвращаемый объект содержит следующие ключи:

• name <string> | <undefined> Имя диапазона в карте исходного кода, если оно указано
• fileName <string> Имя файла исходного кода, указанное в SourceMap
• lineNumber <number> Номер строки соответствующего места вызова в исходном коде с отсчётом от единицы
• columnNumber <number> Номер столбца соответствующего места вызова в исходном коде с отсчётом от единицы