Регистрация синхронных хуков настройки

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

// register-hooks.js
import { registerHooks } from 'node:module';
registerHooks({
  resolve(specifier, context, nextResolve) { /* implementation */ },
  load(url, context, nextLoad) { /* implementation */ },
});

// register-hooks.js
const { registerHooks } = require('node:module');
registerHooks({
  resolve(specifier, context, nextResolve) { /* implementation */ },
  load(url, context, nextLoad) { /* implementation */ },
});

node --import ./register-hooks.js ./my-app.js
node --require ./register-hooks.js ./my-app.js copy

node --import some-package/register ./my-app.js
node --require some-package/register ./my-app.js copy

import { registerHooks } from 'node:module';

registerHooks({ /* implementation of synchronous hooks */ });

// If loaded using static import, the hooks would not be applied when loading
// my-app.mjs, because statically imported modules are all executed before its
// importer regardless of where the static import appears.
// import './my-app.mjs';

// my-app.mjs must be loaded dynamically to ensure the hooks are applied.
await import('./my-app.mjs');

const { registerHooks } = require('node:module');

registerHooks({ /* implementation of synchronous hooks */ });

import('./my-app.mjs');
// Or, if my-app.mjs does not have top-level await or it's a CommonJS module,
// require() can also be used:
// require('./my-app.mjs');

node --import 'data:text/javascript,import {registerHooks} from "node:module"; registerHooks(/* hooks code */);' ./my-app.js copy

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

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

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

Вызвать registerHooks() можно несколько раз:

// entrypoint.mjs
import { registerHooks } from 'node:module';

const hook1 = { /* implementation of hooks */ };
const hook2 = { /* implementation of hooks */ };
// hook2 runs before hook1.
registerHooks(hook1);
registerHooks(hook2);

// entrypoint.cjs
const { registerHooks } = require('node:module');

const hook1 = { /* implementation of hooks */ };
const hook2 = { /* implementation of hooks */ };
// hook2 runs before hook1.
registerHooks(hook1);
registerHooks(hook2);

В этом примере зарегистрированные хуки образуют цепочки. Эти цепочки выполняются в порядке «последним пришёл — первым обслужен» (LIFO). Если и hook1, и hook2 определяют хук resolve, они будут вызваны следующим образом (обратите внимание на порядок справа налево: сначала hook2.resolve, затем hook1.resolve и после этого хук Node.js по умолчанию):

Хук resolve по умолчанию в Node.js ← hook1.resolve ← hook2.resolve

То же относится ко всем остальным хукам.

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

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

Функции-хуки, принимаемые module.registerHooks()

Метод 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.

Синхронный 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>
  • format <string> | <null> | <undefined> Подсказка для хука load (она может быть проигнорирована). Это может быть формат модуля (например, 'commonjs' или 'module') либо произвольное значение, например 'css' или 'yaml'.
  • importAttributes <Object> | <undefined> Атрибуты импорта, используемые при кэшировании модуля (необязательно; если не указаны, будут использованы входные данные)
  • shortCircuit <undefined> | <boolean> Сигнал о том, что этот хук намерен завершить цепочку хуков resolve. По умолчанию: false
  • url <string> Абсолютный URL, в который разрешается этот входной параметр

Цепочка хуков 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.

import { registerHooks } from 'node:module';

function resolve(specifier, context, nextResolve) {
  // When calling `defaultResolve`, the arguments can be modified. For example,
  // to change the specifier or to add applicable export conditions.
  if (specifier.includes('foo')) {
    specifier = specifier.replace('foo', 'bar');
    return nextResolve(specifier, {
      ...context,
      conditions: [...context.conditions, 'another-condition'],
    });
  }

  // The hook can also skip default resolution and provide a custom URL.
  if (specifier === 'special-module') {
    return {
      url: 'file:///path/to/special-module.mjs',
      format: 'module',
      shortCircuit: true,  // This is mandatory if nextResolve() is not called.
    };
  }

  // If no customization is needed, 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);
}

registerHooks({ resolve }); 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 по умолчанию параметр context.format обязателен, если модуль, на который указывает url, не содержит явных сведений о типе модуля.
• Возвращает: <Object>
  • format <string> Один из допустимых форматов модулей, перечисленных ниже.
  • shortCircuit <undefined> | <boolean> Сигнал о том, что этот хук намерен завершить цепочку хуков load. По умолчанию: false
  • source <string> | <ArrayBuffer> | <TypedArray> Исходный код, который Node.js должен выполнить

Хук load позволяет определить пользовательский метод получения исходного кода для разрешённого URL. Это может позволить загрузчику избежать чтения файлов с диска. Также его можно использовать для преобразования нераспознанного формата в поддерживаемый, например yaml в module.

import { registerHooks } from 'node:module';
import { Buffer } from 'node:buffer';

function load(url, context, nextLoad) {
  // The hook can skip default loading and provide a custom source code.
  if (url === 'special-module') {
    return {
      source: 'export const special = 42;',
      format: 'module',
      shortCircuit: true,  // This is mandatory if nextLoad() is not called.
    };
  }

  // It's possible to modify the source code loaded by the next - possibly default - step,
  // for example, replacing 'foo' with 'bar' in the source code of the module.
  const result = nextLoad(url, context);
  const source = typeof result.source === 'string' ?
    result.source : Buffer.from(result.source).toString('utf8');
  return {
    source: source.replace(/foo/g, 'bar'),
    ...result,
  };
}

registerHooks({ resolve }); copy

В более сложных сценариях это также можно использовать для преобразования неподдерживаемого исходного кода в поддерживаемый (см. раздел Примеры ниже).

Ограничения асинхронных хуков настройки

У асинхронных хуков настройки есть множество ограничений, и неизвестно, удастся ли устранить связанные с ними проблемы. Чтобы избежать этих ограничений, пользователям рекомендуется вместо них использовать синхронные хуки настройки через module.registerHooks().

• Асинхронные хуки выполняются в отдельном потоке, поэтому функции хуков не могут напрямую изменять глобальное состояние настраиваемых модулей. Обычно для передачи данных между потоками или управления ходом выполнения используют каналы сообщений и атомарные операции. См. раздел Обмен данными с асинхронными хуками настройки модулей.
• Асинхронные хуки влияют не на все вызовы require() в графе модулей.
  • Пользовательские функции require, созданные с помощью module.createRequire(), не затрагиваются.
  • Если асинхронный хук load не переопределяет source для проходящих через него модулей CommonJS, дочерние модули, загружаемые этими модулями CommonJS через встроенный require(), также не будут затронуты асинхронными хуками.
• При настройке модулей CommonJS асинхронным хукам необходимо учитывать несколько ограничений. Подробности см. в разделах асинхронный хук resolve и асинхронный хук load.
• Когда асинхронные хуки настраивают вызовы require() внутри модулей CommonJS, Node.js может потребоваться несколько раз загрузить исходный код модуля CommonJS, чтобы обеспечить совместимость с существующими механизмами подмены CommonJS. Если код модуля изменится между загрузками, это может привести к неожиданному поведению.
  • В результате, если зарегистрированы и асинхронные, и синхронные хуки, а асинхронные хуки решают настроить модуль CommonJS, синхронные хуки могут вызываться несколько раз для вызовов require() в этом модуле CommonJS.

Регистрация асинхронных хуков настройки

Асинхронные хуки настройки регистрируются с помощью module.register(), которому передаётся путь или URL другого модуля, экспортирующего функции асинхронных хуков.

Как и registerHooks(), register() можно вызвать в модуле, предварительно загруженном с помощью --import или --require, либо непосредственно в точке входа.

// Use module.register() to register asynchronous hooks in a dedicated thread.
import { register } from 'node:module';
register('./hooks.mjs', import.meta.url);

// If my-app.mjs is loaded statically here as `import './my-app.mjs'`, since ESM
// dependencies are evaluated before the module that imports them,
// it's loaded _before_ the hooks are registered above and won't be affected.
// To ensure the hooks are applied, dynamic import() must be used to load ESM
// after the hooks are registered.
import('./my-app.mjs');

const { register } = require('node:module');
const { pathToFileURL } = require('node:url');
// Use module.register() to register asynchronous hooks in a dedicated thread.
register('./hooks.mjs', pathToFileURL(__filename));

import('./my-app.mjs');

В hooks.mjs:

// hooks.mjs
export async function resolve(specifier, context, nextResolve) {
  /* implementation */
}
export async function load(url, context, nextLoad) {
  /* implementation */
} copy

В отличие от синхронных хуков, асинхронные хуки не будут выполняться для этих модулей, загруженных в файле, который вызывает register():

// register-hooks.js
import { register, createRequire } from 'node:module';
register('./hooks.mjs', import.meta.url);

// Asynchronous hooks does not affect modules loaded via custom require()
// functions created by module.createRequire().
const userRequire = createRequire(__filename);
userRequire('./my-app-2.cjs');  // Hooks won't affect this copy

// register-hooks.js
const { register, createRequire } = require('node:module');
const { pathToFileURL } = require('node:url');
register('./hooks.mjs', pathToFileURL(__filename));

// Asynchronous hooks does not affect modules loaded via built-in require()
// in the module calling `register()`
require('./my-app-2.cjs');  // Hooks won't affect this
// .. or custom require() functions created by module.createRequire().
const userRequire = createRequire(__filename);
userRequire('./my-app-3.cjs');  // Hooks won't affect this copy

Асинхронные хуки также можно зарегистрировать с помощью URL data: и флага --import:

node --import 'data:text/javascript,import { register } from "node:module"; import { pathToFileURL } from "node:url"; register("my-instrumentation", pathToFileURL("./"));' ./my-app.js copy

Цепочки асинхронных хуков настройки

Цепочки register() работают аналогично registerHooks(). Если используются и синхронные, и асинхронные хуки, синхронные хуки всегда выполняются первыми, до запуска асинхронных хуков. Иными словами, в последнем выполняемом синхронном хуке его следующий хук включает вызов асинхронных хуков.

// entrypoint.mjs
import { register } from 'node:module';

register('./foo.mjs', import.meta.url);
register('./bar.mjs', import.meta.url);
await import('./my-app.mjs');

// entrypoint.cjs
const { register } = require('node:module');
const { pathToFileURL } = require('node:url');

const parentURL = pathToFileURL(__filename);
register('./foo.mjs', parentURL);
register('./bar.mjs', parentURL);
import('./my-app.mjs');

Если foo.mjs и bar.mjs определяют хук resolve, вызовы будут выполняться в следующем порядке (обратите внимание: справа налево, начиная с ./bar.mjs, затем ./foo.mjs, после чего используется реализация Node.js по умолчанию):

Реализация Node.js по умолчанию ← ./foo.mjs ← ./bar.mjs

При использовании асинхронных хуков зарегистрированные хуки также влияют на последующие вызовы register, которые загружают модули хуков. В приведённом выше примере bar.mjs будет разрешён и загружен с помощью хуков, зарегистрированных через foo.mjs (поскольку хуки foo уже будут добавлены в цепочку). Это позволяет, например, писать хуки на языках, отличных от JavaScript, если ранее зарегистрированные хуки преобразуют их в JavaScript.

Метод register() нельзя вызывать из потока, выполняющего модуль хуков, экспортирующий асинхронные хуки, или его зависимостей.

Обмен данными с асинхронными хуками настройки модулей

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

Метод register можно использовать для передачи данных хуку initialize. Передаваемые хуку данные могут включать передаваемые объекты, например порты.

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

// This example demonstrates how a message channel can be used to
// communicate with the hooks, by sending `port2` to the hooks.
const { port1, port2 } = new MessageChannel();

port1.on('message', (msg) => {
  console.log(msg);
});
port1.unref();

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

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 with the hooks, by sending `port2` to the hooks.
const { port1, port2 } = new MessageChannel();

port1.on('message', (msg) => {
  console.log(msg);
});
port1.unref();

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

Асинхронные хуки, принимаемые 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). По умолчанию они наследуются дочерними рабочими потоками.

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, в который разрешается этот входной параметр

Асинхронная версия работает аналогично синхронной, за исключением того, что функция nextResolve возвращает Promise, а сам хук resolve может возвращать Promise.

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

Предупреждение Хук resolve, вызываемый для вызовов require() внутри модулей CommonJS, настраиваемых асинхронными хуками, не получает исходный спецификатор, переданный в require(). Вместо него он получает URL, уже полностью разрешённый с помощью стандартного механизма разрешения CommonJS.

Предупреждение В модулях CommonJS, настраиваемых асинхронными хуками настройки, require.resolve() и require() будут использовать условие экспорта "import" вместо "require", что может привести к неожиданному поведению при загрузке двойных пакетов.

export async function resolve(specifier, context, nextResolve) {
  // When calling `defaultResolve`, the arguments can be modified. For example,
  // to change the specifier or add conditions.
  if (specifier.includes('foo')) {
    specifier = specifier.replace('foo', 'bar');
    return nextResolve(specifier, {
      ...context,
      conditions: [...context.conditions, 'another-condition'],
    });
  }

  // The hook can also skips default resolution and provide a custom URL.
  if (specifier === 'special-module') {
    return {
      url: 'file:///path/to/special-module.mjs',
      format: 'module',
      shortCircuit: true,  // This is mandatory if not calling nextResolve().
    };
  }

  // If no customization is needed, 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

Асинхронный 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 по умолчанию свойство context.format обязательно, если модуль, на который указывает url, не содержит явных сведений о типе модуля.
• Возвращает: <Promise> Асинхронная версия принимает либо объект со следующими свойствами, либо Promise, который разрешится в такой объект.
  • format <string>
  • shortCircuit <undefined> | <boolean> Сигнал о том, что этот хук намерен завершить цепочку хуков load. По умолчанию: false
  • source <string> | <ArrayBuffer> | <TypedArray> Исходный код, который должен выполнить Node.js

Предупреждение: Асинхронный хук load несовместим с именованными экспортами из модулей CommonJS. При их совместном использовании импорт вернёт пустой объект. В будущем это ограничение может быть устранено. Оно не относится к синхронному хуку load, при использовании которого экспорты работают как обычно.

Асинхронная версия работает аналогично синхронной, однако при использовании асинхронного хука load указание или пропуск source для 'commonjs' приводит к совершенно разным результатам:

• Если указано значение source, все вызовы require из этого модуля будут обрабатываться загрузчиком ESM с зарегистрированными хуками resolve и load; все вызовы require.resolve из этого модуля будут обрабатываться загрузчиком ESM с зарегистрированными хуками resolve; будет доступна только часть API CommonJS (например, без require.extensions, без require.cache, без require.resolve.paths), а подмена загрузчика модулей CommonJS применяться не будет.
• Если source имеет значение undefined или null, модуль будет обрабатываться загрузчиком CommonJS, а вызовы require/require.resolve не будут проходить через зарегистрированные хуки. Такое поведение для пустых значений source временное — в будущем пустые значения source не будут поддерживаться.

Эти ограничения не относятся к синхронному хуку load: в этом случае настраиваемым модулям CommonJS доступен полный набор API CommonJS, а вызовы require/require.resolve всегда проходят через зарегистрированные хуки.

Внутренняя асинхронная реализация load в Node.js, являющаяся значением next для последнего хука в цепочке load, возвращает null для source, если format имеет значение 'commonjs', для обеспечения обратной совместимости. Ниже приведён пример хука, который явно включает нестандартное поведение:

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

Это также не относится к синхронному хуку load: в этом случае возвращаемое значение source содержит исходный код, загруженный следующим хуком, независимо от формата модуля.

Импорт по 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> Номер столбца соответствующего места вызова в исходном коде с нумерацией от единицы