Обработка событий

Объект process является экземпляром EventEmitter.

Событие: 'beforeExit'

Событие 'beforeExit' генерируется, когда процесс Node.js очищает свой цикл событий и не имеет дополнительных задач для планирования. Обычно процесс Node.js завершается, когда нет запланированных задач, но обработчик, зарегистрированный для события 'beforeExit' , может выполнять асинхронные вызовы и, таким образом, заставить процесс Node.js продолжить работу.

Обработчик вызывается с значением process.exitCode в качестве единственного аргумента.

Событие 'beforeExit' не генерируется для условий явного завершения, таких как вызов process.exit() или необработанных исключений.

Событие 'beforeExit' не следует использовать в качестве альтернативы событию 'exit' , если только не планируется выполнить дополнительные задачи.

process.on('beforeExit', (code) => {
  console.log('Process beforeExit event with code: ', code);
});

process.on('exit', (code) => {
  console.log('Process exit event with code: ', code);
});

console.log('This message is displayed first.');

// Prints:
// This message is displayed first.
// Process beforeExit event with code: 0
// Process exit event with code: 0

Событие: 'disconnect'

Если процесс Node.js запущен с каналом IPC (см. документацию Процесс-потомка и Кластер), событие 'disconnect' будет сгенерировано при закрытии канала IPC.

Событие: 'exit'

• code <целое>

Событие 'exit' генерируется, когда процесс Node.js собирается завершиться в результате:

• Явного вызова метода process.exit();
• Отсутствия дополнительных задач в цикле событий Node.js.

В этот момент невозможно предотвратить завершение цикла событий, и процесс Node.js завершится после выполнения всех обработчиков событий 'exit'.

Обработчик вызывается с кодом завершения, указанным либо свойством process.exitCode, либо аргументом exitCode , переданным методу process.exit().

process.on('exit', (code) => {
  console.log(`About to exit with code: ${code}`);
});

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

process.on('exit', (code) => {
  setTimeout(() => {
    console.log('This will not run');
  }, 0);
});

Событие: 'message'

• message <Объект> | <логическое> | <число> | <строка> | <null> — разобранный объект JSON или сериализуемое примитивное значение.
• sendHandle <net.Server> | <net.Socket> — объект net.Server или net.Socket, или undefined.

Если процесс Node.js запущен с каналом IPC (см. документацию Процесс-потомка и Кластер), событие 'message' генерируется всякий раз, когда в дочерний процесс принимается сообщение, отправленное родительским процессом с помощью childprocess.send().

Сообщение проходит сериализацию и парсинг. Результирующее сообщение может отличаться от исходного.

Если опция serialization была установлена в значение advanced при запуске процесса, аргумент message может содержать данные, которые JSON не может представить. Подробнее см. Расширенная сериализация для child_process.

Событие: 'multipleResolves'

• type <строка> Тип разрешения. Один из 'resolve' или 'reject'.
• promise <Promise> Promise, который разрешался или отклонялся более одного раза.
• value <любое> Значение, с помощью которого promise был разрешен или отклонен после первоначального разрешения.

Событие 'multipleResolves' генерируется всякий раз, когда Promise:

• Разрешается более одного раза.
• Отклоняется более одного раза.
• Отклоняется после разрешения.
• Разрешается после отклонения.

Это полезно для отслеживания потенциальных ошибок в приложении при использовании конструктора Promise, поскольку множественные разрешения бесшумно игнорируются. Однако возникновение этого события не обязательно указывает на ошибку. Например, Promise.race() может вызвать событие 'multipleResolves'.

process.on('multipleResolves', (type, promise, reason) => {
  console.error(type, promise, reason);
  setImmediate(() => process.exit(1));
});

async function main() {
  try {
    return await new Promise((resolve, reject) => {
      resolve('First call');
      resolve('Swallowed resolve');
      reject(new Error('Swallowed reject'));
    });
  } catch {
    throw new Error('Failed');
  }
}

main().then(console.log);
// resolve: Promise { 'First call' } 'Swallowed resolve'
// reject: Promise { 'First call' } Error: Swallowed reject
//     at Promise (*)
//     at new Promise (<anonymous>)
//     at main (*)
// First call

Событие: 'rejectionHandled'

• promise <Promise> Отложенный promise.

Событие 'rejectionHandled' генерируется всякий раз, когда Promise отклоняется, и к нему позднее (после одного цикла Node.js) прикрепляется обработчик ошибок (например, с помощью promise.catch()).

Объект Promise ранее был сгенерирован в событии 'unhandledRejection', но в ходе обработки к нему был добавлен обработчик отклонения.

Нет концепции верхнего уровня для цепочки Promise, в котором отклонения всегда могут быть обработаны. По своей природе асинхронные, отклонение Promise может быть обработано в будущем, возможно, намного позже цикла событий, в котором генерируется событие 'unhandledRejection'.

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

В синхронном коде событие 'uncaughtException' генерируется, когда список необработанных исключений увеличивается.

В асинхронном коде событие 'unhandledRejection' генерируется, когда список необработанных отклонений увеличивается, а событие 'rejectionHandled' генерируется, когда список необработанных отклонений уменьшается.

const unhandledRejections = new Map();
process.on('unhandledRejection', (reason, promise) => {
  unhandledRejections.set(promise, reason);
});
process.on('rejectionHandled', (promise) => {
  unhandledRejections.delete(promise);
});

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

Событие: 'uncaughtException'

• err <Ошибка> Необработанное исключение.
• origin <строка> Указывает, происходит ли исключение из-за необработанного отклонения или синхронной ошибки. Может быть 'uncaughtException' или 'unhandledRejection'. Последнее используется только в сочетании со флагом --unhandled-rejections, установленным в strict или throw и необработанным отклонением.

Событие 'uncaughtException' генерируется, когда необработанное исключение JavaScript возвращается в цикл событий. По умолчанию Node.js обрабатывает такие исключения, выводит трассировку стека в stderr и завершается с кодом 1, перезаписывая ранее установленный process.exitCode. Добавление обработчика для события 'uncaughtException' переопределяет это поведение по умолчанию. В противном случае, если обработчик присутствует, процесс завершится с кодом 0.

process.on('uncaughtException', (err, origin) => {
  fs.writeSync(
    process.stderr.fd,
    `Caught exception: ${err}\n` +
    `Exception origin: ${origin}`
  );
});

setTimeout(() => {
  console.log('This will still run.');
}, 500);

// Intentionally cause an exception, but don't catch it.
nonexistentFunc();
console.log('This will not run.');

Можно отслеживать события 'uncaughtException' без переопределения поведения по умолчанию, завершающего процесс, установив обработчик события 'uncaughtExceptionMonitor'.

Предупреждение: Правильное использование 'uncaughtException'

'uncaughtException' — это грубый механизм обработки исключений, который следует использовать только в крайних случаях. Событие не следует использовать как эквивалент On Error Resume Next. Необработанные исключения подразумевают, что приложение находится в неопределенном состоянии. Попытка продолжить выполнение кода приложения без правильного восстановления после исключения может привести к дополнительным непредвиденным и непредсказуемым проблемам.

Исключения, сгенерированные внутри обработчика событий, не будут перехвачены. Вместо этого процесс завершится с ненулевым кодом выхода, и будет выведена трассировка стека. Это сделано для предотвращения бесконечной рекурсии.

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

Правильное использование 'uncaughtException' — выполнить синхронную очистку выделенных ресурсов (например, дескрипторов файлов, дескрипторов и т. д.) перед завершением процесса. Не безопасно возобновлять нормальную работу после 'uncaughtException'.

Для более надежного перезапуска аварийного приложения, независимо от того, выводится ли событие 'uncaughtException' или нет, следует использовать внешний монитор в отдельном процессе для обнаружения сбоев приложения и восстановления или перезапуска по мере необходимости.

Событие: 'uncaughtExceptionMonitor'

• err <Ошибка> Необработанное исключение.
• origin <строка> Указывает, произошло ли исключение из-за необработанного обещания или синхронных ошибок. Может быть 'uncaughtException' или 'unhandledRejection'. Последнее используется только в сочетании с флагом --unhandled-rejections, установленным в значение strict или throw, и необработанным обещанием.

Событие 'uncaughtExceptionMonitor' генерируется до генерации события 'uncaughtException' или вызова обработчика, установленного через process.setUncaughtExceptionCaptureCallback().

Установка обработчика события 'uncaughtExceptionMonitor' не меняет поведение после генерации события 'uncaughtException'. Процесс всё равно завершится аварийно, если обработчик события 'uncaughtException' не установлен.

process.on('uncaughtExceptionMonitor', (err, origin) => {
  MyMonitoringTool.logSync(err, origin);
});

// Intentionally cause an exception, but don't catch it.
nonexistentFunc();
// Still crashes Node.js

Событие: 'unhandledRejection'

• reason <Ошибка> | <любой> Объект, с помощью которого обещание было отклонено (обычно объект Error).
• promise <Обещание> Отклоненное обещание.

Событие 'unhandledRejection' генерируется всякий раз, когда обещание Promise отклоняется, и к нему не прикреплен обработчик ошибок в течение одного цикла обработки событий. При программировании с обещаниями исключения инкапсулируются в виде «отклоненных обещаний». Отклонения можно перехватывать и обрабатывать с помощью promise.catch(), и они передаются через цепочку Promise обещаний. Событие 'unhandledRejection' полезно для обнаружения и отслеживания отклоненных обещаний, обработка которых ещё не выполнена.

process.on('unhandledRejection', (reason, promise) => {
  console.log('Unhandled Rejection at:', promise, 'reason:', reason);
  // Application specific logging, throwing an error, or other logic here
});

somePromise.then((res) => {
  return reportToUser(JSON.pasre(res)); // Note the typo (`pasre`)
}); // No `.catch()` or `.then()`

Следующее также вызовет генерацию события 'unhandledRejection':

function SomeResource() {
  // Initially set the loaded status to a rejected promise
  this.loaded = Promise.reject(new Error('Resource not yet loaded!'));
}

const resource = new SomeResource();
// no .catch or .then on resource.loaded for at least a turn

В этом примере можно отследить отклонение как ошибку разработчика, как обычно делается для других событий 'unhandledRejection'. Для решения таких проблем может быть прикреплен неработающий обработчик .catch(() => { }) к resource.loaded, который предотвратит генерацию события 'unhandledRejection'.

Событие: 'warning'

• warning <Ошибка> Ключевые свойства предупреждения:
  • name <строка> Название предупреждения. По умолчанию: 'Warning'.
  • message <строка> Описание предупреждения, предоставленное системой.
  • stack <строка> Трассировка стека до места в коде, где было выведено предупреждение.

Событие 'warning' генерируется всякий раз, когда Node.js генерирует предупреждение процесса.

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

process.on('warning', (warning) => {
  console.warn(warning.name);    // Print the warning name
  console.warn(warning.message); // Print the warning message
  console.warn(warning.stack);   // Print the stack trace
});

По умолчанию, Node.js выводит предупреждения процесса в stderr. Флаг командной строки --no-warnings можно использовать для подавления стандартного вывода в консоль, но событие 'warning' всё ещё будет генерироваться объектом process.

Следующий пример демонстрирует предупреждение, которое выводится в stderr при добавлении слишком большого количества обработчиков события:

$ node
> events.defaultMaxListeners = 1;
> process.on('foo', () => {});
> process.on('foo', () => {});
> (node:38638) MaxListenersExceededWarning: Possible EventEmitter memory leak
detected. 2 foo listeners added. Use emitter.setMaxListeners() to increase limit

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

$ node --no-warnings
> const p = process.on('warning', (warning) => console.warn('Do not do that!'));
> events.defaultMaxListeners = 1;
> process.on('foo', () => {});
> process.on('foo', () => {});
> Do not do that!

Флаг командной строки --trace-warnings позволяет включать полную трассировку стека предупреждений в стандартный вывод.

Запуск Node.js с флагом командной строки --throw-deprecation вызовет генерацию пользовательских предупреждений об устаревании как исключений.

Использование флага командной строки --trace-deprecation выведет пользовательские предупреждения об устаревании в stderr вместе с трассировкой стека.

Использование флага командной строки --no-deprecation подавит все сообщения о пользовательских предупреждениях об устаревании.

Флаги командной строки *-deprecation влияют только на предупреждения, использующие имя 'DeprecationWarning'.

Генерация пользовательских предупреждений

См. метод process.emitWarning() для выдачи пользовательских или специфичных для приложения предупреждений.

Названия предупреждений Node.js

Нет строгих правил для типов предупреждений (как определяется свойством name), генерируемых Node.js. Новые типы предупреждений могут быть добавлены в любое время. Некоторые из наиболее распространённых типов предупреждений включают:

• 'DeprecationWarning' - Указывает на использование устаревшего API или функции Node.js. Такие предупреждения должны включать свойство 'code', определяющее код устаревания.
• 'ExperimentalWarning' - Указывает на использование экспериментального API или функции Node.js. Такие функции следует использовать с осторожностью, так как они могут измениться в любое время и не имеют таких же строгих политик семантического выпуска и долгосрочной поддержки, как поддерживаемые функции.
• 'MaxListenersExceededWarning' - Указывает на то, что для данного события зарегистрировано слишком много обработчиков на EventEmitter или EventTarget. Это часто указывает на утечку памяти.
• 'TimeoutOverflowWarning' - Указывает, что числовое значение, которое не помещается в 32-битное знаковое целое число, было предоставлено функциям setTimeout() или setInterval().
• 'UnsupportedWarning' - Указывает на использование неподдерживаемого параметра или функции, которые будут проигнорированы, а не считаться ошибкой. Одним из примеров является использование сообщения о статусе HTTP-ответа при использовании совместимого API HTTP/2.

События сигналов

События сигналов будут генерироваться, когда процесс Node.js получит сигнал. Обратитесь к signal(7) для списка стандартных имён сигналов POSIX, таких как 'SIGINT', 'SIGHUP', и т. д.

Сигналы недоступны для потоков Worker.

Обработчик сигнала получит имя сигнала ('SIGINT', 'SIGTERM', и т. д.) в качестве первого аргумента.

Имя каждого события будет верхним регистром общего имени сигнала (например, 'SIGINT' для SIGINT сигналов).

// Begin reading from stdin so the process does not exit.
process.stdin.resume();

process.on('SIGINT', () => {
  console.log('Received SIGINT. Press Control-D to exit.');
});

// Using a single function to handle multiple signals
function handle(signal) {
  console.log(`Received ${signal}`);
}

process.on('SIGINT', handle);
process.on('SIGTERM', handle);

• 'SIGUSR1' зарезервирован Node.js для запуска отладчика debugger. Возможно установка обработчика, но это может повлиять на отладчик.
• 'SIGTERM' и 'SIGINT' имеют обработчики по умолчанию на платформах, отличных от Windows, которые сбрасывают режим терминала перед завершением с кодом 128 + signal number. Если для одного из этих сигналов установлен обработчик, его поведение по умолчанию будет удалено (Node.js больше не завершится).
• 'SIGPIPE' игнорируется по умолчанию. Для него может быть установлен обработчик.
• 'SIGHUP' генерируется на Windows, когда закрывается окно консоли, и на других платформах в различных аналогичных условиях. См. signal(7). Для него может быть установлен обработчик, но Node.js будет безусловно завершен через 10 секунд Windows. На платформах, отличных от Windows, по умолчанию SIGHUP завершает Node.js, но после установки обработчика его поведение по умолчанию будет удалено.
• 'SIGTERM' не поддерживается в Windows, для него можно установить обработчик.
• 'SIGINT' из терминала поддерживается на всех платформах и обычно генерируется нажатием Ctrl+C (хотя это может быть настраиваемо). Он не генерируется, когда включён режим сырого режима терминала и используется Ctrl+C.
• 'SIGBREAK' доставляется в Windows при нажатии Ctrl+Break. На платформах, отличных от Windows, для него можно установить обработчик, но нет способа отправить или сгенерировать его.
• 'SIGWINCH' доставляется, когда консоль была переразмеренна. В Windows это произойдёт только при записи в консоль при перемещении курсора или использовании читаемого tty в сыром режиме.
• 'SIGKILL' не может иметь обработчика, он безусловно завершит Node.js на всех платформах.
• 'SIGSTOP' не может иметь обработчика.
• 'SIGBUS', 'SIGFPE', 'SIGSEGV' и 'SIGILL', если они не были искусственно подняты с помощью kill(2), оставляют процесс в состоянии, при котором вызов обработчиков JS небезопасен. Это может привести к остановке отклика процесса.
• 0 можно отправить для проверки существования процесса. Он не оказывает влияния, если процесс существует, но вызовет ошибку, если процесс не существует.

Windows не поддерживает сигналы, поэтому не имеет эквивалента завершения сигналом, но Node.js предлагает некоторую эмуляцию с помощью process.kill() и subprocess.kill():

• Отправка SIGINT, SIGTERM, и SIGKILL вызовет безусловное завершение целевого процесса, после чего дочерний процесс сообщит, что процесс был завершен сигналом.
• Отправка сигнала 0 может использоваться в качестве платформенно-независимого способа проверки существования процесса.

process.abort()

Метод process.abort() вызывает немедленное завершение процесса Node.js и создание файла core.

Эта функция недоступна в потоках Worker.

process.allowedNodeEnvironmentFlags

• <Set>

Свойство process.allowedNodeEnvironmentFlags — специальный, только для чтения, Set разрешённых флагов в среде NODE_OPTIONS.

process.allowedNodeEnvironmentFlags расширяет Set, но переопределяет Set.prototype.has для распознавания нескольких различных представлений флагов. process.allowedNodeEnvironmentFlags.has() вернёт true в следующих случаях:

• Флаги могут опускать ведущие одинарные (-) или двойные (--) дефисы; например, inspect-brk для --inspect-brk, или r для -r.
• Флаги, передаваемые в V8 (как указано в --v8-options), могут заменить один или несколько не ведущих дефисов подчёркиванием, или наоборот; например, --perf_basic_prof, --perf-basic-prof, --perf_basic-prof, и т.д.
• Флаги могут содержать один или несколько символов равно (=); все символы после и включая первый символ равно будут проигнорированы; например, --stack-trace-limit=100.
• Флаги должны быть разрешены в NODE_OPTIONS.

При итерировании по process.allowedNodeEnvironmentFlags, флаги будут отображаться только один раз; каждый из них начнется с одного или нескольких дефисов. Переданные в V8 флаги будут содержать подчёркивания вместо не ведущих дефисов:

process.allowedNodeEnvironmentFlags.forEach((flag) => {
  // -r
  // --inspect-brk
  // --abort_on_uncaught_exception
  // ...
});

Методы add(), clear(), и delete() объекта process.allowedNodeEnvironmentFlags ничего не делают и завершаются молчаливо.

Если Node.js был скомпилирован без поддержки NODE_OPTIONS (показано в process.config), process.allowedNodeEnvironmentFlags будет содержать то, что могло бы быть допустимо.

process.arch

• <string>

Архитектура процессора операционной системы, для которой был скомпилирован двоичный файл Node.js. Возможные значения: 'arm', 'arm64', 'ia32', 'mips','mipsel', 'ppc', 'ppc64', 's390', 's390x', 'x32', и 'x64'.

console.log(`This processor architecture is ${process.arch}`);

process.argv

• <string[]>

Свойство process.argv возвращает массив, содержащий аргументы командной строки, переданные при запуске процесса Node.js. Первый элемент будет process.execPath. См. process.argv0, если необходим доступ к исходному значению argv[0]. Второй элемент — путь к исполняемому файлу JavaScript. Остальные элементы — дополнительные аргументы командной строки.

Например, предположим следующий скрипт для process-args.js:

// print process.argv
process.argv.forEach((val, index) => {
  console.log(`${index}: ${val}`);
});

Запуск процесса Node.js как:

$ node process-args.js one two=three four

Выведет:

0: /usr/local/bin/node
1: /Users/mjr/work/node/process-args.js
2: one
3: two=three
4: four

process.argv0

• <string>

Свойство process.argv0 хранит только для чтения копию исходного значения argv[0] переданного при запуске Node.js.

$ bash -c 'exec -a customArgv0 ./node'
> process.argv[0]
'/Volumes/code/external/node/out/Release/node'
> process.argv0
'customArgv0'

process.channel

• <Object>

Если процесс Node.js был запущен с каналом IPC (см. документацию по дочерним процессам), свойство process.channel ссылается на канал IPC. Если канал IPC отсутствует, это свойство — undefined.

process.channel.ref()

Этот метод заставляет канал IPC удерживать цикл событий процесса, если .unref() был вызван ранее.

Как правило, это управляется количеством слушателей 'disconnect' и 'message' объекта process. Однако этот метод может использоваться для явного запроса определенного поведения.

process.channel.unref()

Этот метод заставляет канал IPC не удерживать цикл событий процесса и позволяет ему завершиться, даже если канал открыт.

Как правило, это управляется количеством слушателей 'disconnect' и 'message' объекта process. Однако этот метод может использоваться для явного запроса определенного поведения.

process.chdir(directory)

• directory <string>

Метод process.chdir() изменяет текущий рабочий каталог процесса Node.js или генерирует исключение, если это изменение невозможно (например, если указанный directory не существует).

console.log(`Starting directory: ${process.cwd()}`);
try {
  process.chdir('/tmp');
  console.log(`New directory: ${process.cwd()}`);
} catch (err) {
  console.error(`chdir: ${err}`);
}

Эта функция недоступна в потоках Worker.

process.config

• <Object>

Свойство process.config возвращает Object, содержащий JavaScript-представление опций конфигурации, используемых для компиляции текущего исполняемого файла Node.js. Это то же самое, что и файл config.gypi, который был создан при запуске скрипта ./configure.

Пример возможного вывода:

{
  target_defaults:
   { cflags: [],
     default_configuration: 'Release',
     defines: [],
     include_dirs: [],
     libraries: [] },
  variables:
   {
     host_arch: 'x64',
     napi_build_version: 5,
     node_install_npm: 'true',
     node_prefix: '',
     node_shared_cares: 'false',
     node_shared_http_parser: 'false',
     node_shared_libuv: 'false',
     node_shared_zlib: 'false',
     node_use_dtrace: 'false',
     node_use_openssl: 'true',
     node_shared_openssl: 'false',
     strict_aliasing: 'true',
     target_arch: 'x64',
     v8_use_snapshot: 1
   }
}

Свойство process.config не является только для чтения, и существуют модули в экосистеме, которые известны тем, что расширяют, изменяют или полностью заменяют значение process.config.

process.connected

• <boolean>

Если процесс Node.js запущен с каналом IPC (см. документацию по дочерним процессам и кластерам), свойство process.connected вернёт true, пока канал IPC подключен, и вернёт false после вызова process.disconnect().

После того, как process.connected станет false, отправка сообщений по каналу IPC с помощью process.send() больше невозможна.

process.cpuUsage([previousValue])

• previousValue <Object> Предыдущее значение, возвращённое вызовом process.cpuUsage()
• Возвращает: <Object>
  • user <integer>
  • system <integer>

Метод process.cpuUsage() возвращает использование процессорного времени (пользовательское и системное) текущим процессом в виде объекта с свойствами user и system, значения которых выражены в микросекундах (миллионных долях секунды). Эти значения измеряют время, потраченное в пользовательском и системном коде соответственно, и могут оказаться больше фактического времени, если несколько ядер процессора выполняют работу для этого процесса.

Результат предыдущего вызова process.cpuUsage() можно передать в функцию в качестве аргумента, чтобы получить разницу.

const startUsage = process.cpuUsage();
// { user: 38579, system: 6986 }

// spin the CPU for 500 milliseconds
const now = Date.now();
while (Date.now() - now < 500);

console.log(process.cpuUsage(startUsage));
// { user: 514883, system: 11226 }

process.cwd()

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

Метод process.cwd() возвращает текущий рабочий каталог процесса Node.js.

console.log(`Current directory: ${process.cwd()}`);

process.debugPort

• <number>

Порт, используемый отладчиком Node.js при его включении.

process.debugPort = 5858;

process.disconnect()

Если процесс Node.js запущен с каналом IPC (см. документацию по Процессам-потомкам и Кластеризации), метод process.disconnect() закроет канал IPC с родительским процессом, что позволит дочернему процессу выйти корректно, когда больше нет других соединений, которые его поддерживают.

Результат вызова process.disconnect() такой же, как вызов ChildProcess.disconnect() из родительского процесса.

Если процесс Node.js не был запущен с каналом IPC, process.disconnect() будет undefined.

process.dlopen(module, filename[, flags])

• module <Объект>
• filename <строка>
• flags <os.constants.dlopen> По умолчанию: os.constants.dlopen.RTLD_LAZY

Метод process.dlopen() позволяет динамически загружать общие объекты. Он используется в основном модулем require() для загрузки C++-надстроек и не должен использоваться напрямую, кроме специальных случаев. Другими словами, require() предпочтительнее process.dlopen() , если нет особых причин, таких как настраиваемые флаги dlopen или загрузка из модулей ES.

Аргумент flags — целое число, которое позволяет указать поведение dlopen. Подробности см. в документации os.constants.dlopen.

Важное требование при вызове process.dlopen() — необходимо передать экземпляр module. Затем функции, экспортированные C++-надстройкой, становятся доступны через module.exports.

В примере ниже показано, как загрузить C++-надстройку под названием local.node, которая экспортирует функцию foo. Все символы загружаются до возврата вызова путём передачи константы RTLD_NOW. В этом примере предполагается, что константа доступна.

const os = require('os');
const path = require('path');
const module = { exports: {} };
process.dlopen(module, path.join(__dirname, 'local.node'),
               os.constants.dlopen.RTLD_NOW);
module.exports.foo();

process.emitWarning(warning[, options])

• warning <строка> | <Ошибка> Предупреждение для вывода.
• options <Объект>
  • type <строка> Если warning является строкой, type — имя, используемое для типа выводимого предупреждения. По умолчанию: 'Warning'.
  • code <строка> Уникальный идентификатор экземпляра предупреждения, которое выводится.
  • ctor <Функция> Если warning является функцией, ctor — необязательная функция, используемая для ограничения генерируемого трассировки стека. По умолчанию: process.emitWarning.
  • detail <строка> Дополнительный текст для включения с ошибкой.

Метод process.emitWarning() можно использовать для вывода пользовательских или прикладных предупреждений процесса. На эти предупреждения можно реагировать, добавив обработчик в событие 'warning'.

// Emit a warning with a code and additional detail.
process.emitWarning('Something happened!', {
  code: 'MY_WARNING',
  detail: 'This is some additional information'
});
// Emits:
// (node:56338) [MY_WARNING] Warning: Something happened!
// This is some additional information

В этом примере объект Error генерируется внутри process.emitWarning() и передаётся обработчику события 'warning'.

process.on('warning', (warning) => {
  console.warn(warning.name);    // 'Warning'
  console.warn(warning.message); // 'Something happened!'
  console.warn(warning.code);    // 'MY_WARNING'
  console.warn(warning.stack);   // Stack trace
  console.warn(warning.detail);  // 'This is some additional information'
});

Если warning передаётся как объект Error, аргумент options игнорируется.

process.emitWarning(warning[, type[, code]][, ctor])

• warning <строка> | <Ошибка> Предупреждение для вывода.
• type <строка> Если warning является строкой, type — имя, используемое для типа выводимого предупреждения. По умолчанию: 'Warning'.
• code <строка> Уникальный идентификатор экземпляра предупреждения, которое выводится.
• ctor <Функция> Если warning является функцией, ctor — необязательная функция, используемая для ограничения генерируемого трассировки стека. По умолчанию: process.emitWarning.

Метод process.emitWarning() может использоваться для вывода пользовательских или прикладных предупреждений процесса. На эти предупреждения можно реагировать, добавив обработчик в событие 'warning'.

// Emit a warning using a string.
process.emitWarning('Something happened!');
// Emits: (node: 56338) Warning: Something happened!

// Emit a warning using a string and a type.
process.emitWarning('Something Happened!', 'CustomWarning');
// Emits: (node:56338) CustomWarning: Something Happened!

process.emitWarning('Something happened!', 'CustomWarning', 'WARN001');
// Emits: (node:56338) [WARN001] CustomWarning: Something happened!

В каждом из предыдущих примеров объект Error генерируется внутри process.emitWarning() и передаётся обработчику события 'warning'.

process.on('warning', (warning) => {
  console.warn(warning.name);
  console.warn(warning.message);
  console.warn(warning.code);
  console.warn(warning.stack);
});

Если warning передаётся как объект Error, он передаётся обработчику события 'warning' без изменений (а необязательные аргументы type, code и ctor игнорируются):

// Emit a warning using an Error object.
const myWarning = new Error('Something happened!');
// Use the Error name property to specify the type name
myWarning.name = 'CustomWarning';
myWarning.code = 'WARN001';

process.emitWarning(myWarning);
// Emits: (node:56338) [WARN001] CustomWarning: Something happened!

Возникает ошибка TypeError, если warning является чем-то кроме строки или объекта Error.

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

Следующая дополнительная обработка выполняется, если предупреждение type равно 'DeprecationWarning':

• Если используется флаг командной строки --throw-deprecation, предупреждение об устаревании выводится как исключение, а не как событие.
• Если используется флаг командной строки --no-deprecation, предупреждение об устаревании подавляется.
• Если используется флаг командной строки --trace-deprecation, предупреждение об устаревании печатается в stderr вместе с полной трассировкой стека.

Избегание дублирующих предупреждений

В качестве рекомендации, предупреждения должны выводиться только один раз на процесс. Для этого рекомендуется поместить emitWarning() за простой логической переменной, как показано в примере ниже:

function emitMyWarning() {
  if (!emitMyWarning.warned) {
    emitMyWarning.warned = true;
    process.emitWarning('Only warn once!');
  }
}
emitMyWarning();
// Emits: (node: 56339) Warning: Only warn once!
emitMyWarning();
// Emits nothing

process.env

• <Объект>

Свойство process.env возвращает объект, содержащий пользовательскую среду. См. environ(7).

Пример этого объекта:

{
  TERM: 'xterm-256color',
  SHELL: '/usr/local/bin/bash',
  USER: 'maciej',
  PATH: '~/.bin/:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin',
  PWD: '/Users/maciej',
  EDITOR: 'vim',
  SHLVL: '1',
  HOME: '/Users/maciej',
  LOGNAME: 'maciej',
  _: '/usr/local/bin/node'
}

Можно изменить этот объект, но такие изменения не будут отражены за пределами процесса Node.js или (если не запрошено явно) в других потоках Worker. Другими словами, следующий пример не сработает:

$ node -e 'process.env.foo = "bar"' && echo $foo

Однако следующий пример сработает:

process.env.foo = 'bar';
console.log(process.env.foo);

Присвоение свойства объекту process.env неявно преобразует значение в строку. Это поведение устарело. В будущих версиях Node.js может возникнуть ошибка, если значение не является строкой, числом или булевым значением.

process.env.test = null;
console.log(process.env.test);
// => 'null'
process.env.test = undefined;
console.log(process.env.test);
// => 'undefined'

Используйте delete для удаления свойства из process.env.

process.env.TEST = 1;
delete process.env.TEST;
console.log(process.env.TEST);
// => undefined

В операционных системах Windows переменные окружения нечувствительны к регистру.

process.env.TEST = 1;
console.log(process.env.test);
// => 1

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

process.execArgv

• <string[]>

Свойство process.execArgv возвращает набор параметров командной строки, специфичных для Node.js, переданных при запуске процесса Node.js. Эти параметры не отображаются в массиве, возвращаемом свойством process.argv, и не включают исполняемый файл Node.js, имя скрипта или параметры, следующие за именем скрипта. Эти параметры полезны для запуска дочерних процессов с такой же средой выполнения, как у родительского.

$ node --harmony script.js --version

Результатом является process.execArgv:

['--harmony']

И process.argv:

['/usr/local/bin/node', 'script.js', '--version']

Обратитесь к Worker конструктору для подробного описания поведения потоков-рабочих с этим свойством.

process.execPath

• <string>

Свойство process.execPath возвращает абсолютный путь к исполняемому файлу, который запустил процесс Node.js. Символические ссылки, если таковые имеются, будут разрешены.

'/usr/local/bin/node'

process.exit([code])

• code <integer> Код завершения. По умолчанию: 0.

Метод process.exit() указывает Node.js на синхронное завершение процесса со статусом завершения code. Если code опущено, используется код «успеха» 0 или значение свойства process.exitCode , если оно было установлено. Node.js не завершит работу до тех пор, пока не будут вызваны все обработчики события 'exit'.

Для выхода с кодом «ошибка»:

process.exit(1);

Оболочка, которая выполнила Node.js, должна увидеть код завершения как 1.

Вызов process.exit() заставит процесс выйти как можно быстрее, даже если остались ожидающие асинхронные операции, которые ещё не завершились полностью, включая операции ввода-вывода в process.stdout и process.stderr.

В большинстве случаев явное обращение к process.exit() не требуется. Процесс Node.js завершится сам если в очереди событий нет дополнительных задач. Свойство process.exitCode можно установить, чтобы указать код завершения, используемый при нормальном выходе процесса.

Например, следующий пример иллюстрирует неправильное использование метода process.exit(), которое может привести к усечению и потере данных, выведенных в stdout:

// This is an example of what *not* to do:
if (someConditionNotMet()) {
  printUsageToStdout();
  process.exit(1);
}

Причина, по которой это проблема, заключается в том, что запись в process.stdout в Node.js иногда асинхронна и может происходить на протяжении нескольких тактов очереди событий Node.js. Однако вызов process.exit(), заставляет процесс завершиться до выполнения дополнительных записей в stdout.

Вместо прямого вызова process.exit(), код должен установить свойство process.exitCode и позволить процессу завершиться естественным путём, избегая планирования дополнительных задач для очереди событий:

// How to properly set the exit code while letting
// the process exit gracefully.
if (someConditionNotMet()) {
  printUsageToStdout();
  process.exitCode = 1;
}

Если необходимо завершить процесс Node.js из-за ошибки, безопаснее сгенерировать неперехваченную ошибку и позволить процессу завершиться соответственно, чем вызывать process.exit().

В потоках Worker эта функция останавливает текущий поток, а не текущий процесс.

process.exitCode

• <integer>

Число, которое будет кодом завершения процесса, когда процесс завершается нормально или завершается через process.exit() без указания кода.

Указание кода для process.exit(code) переопределит любое предыдущее значение свойства process.exitCode.

process.getegid()

Метод process.getegid() возвращает числовое значение эффективного идентификатора группы процесса Node.js. (См. getegid(2).)

if (process.getegid) {
  console.log(`Current gid: ${process.getegid()}`);
}

Эта функция доступна только на платформах POSIX (т. е. не на Windows или Android).

process.geteuid()

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

Метод process.geteuid() возвращает числовое значение эффективного идентификатора пользователя процесса. (См. geteuid(2).)

if (process.geteuid) {
  console.log(`Current uid: ${process.geteuid()}`);
}

Эта функция доступна только на платформах POSIX (т. е. не на Windows или Android).

process.getgid()

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

Метод process.getgid() возвращает числовое значение идентификатора группы процесса. (См. getgid(2).)

if (process.getgid) {
  console.log(`Current gid: ${process.getgid()}`);
}

Эта функция доступна только на платформах POSIX (т. е. не на Windows или Android).

process.getgroups()

• Возвращает: <integer[]>

Метод process.getgroups() возвращает массив с дополнительными идентификаторами групп. Стандарт POSIX не оговаривает, включается ли эффективный идентификатор группы, но Node.js гарантирует, что он всегда включается.

if (process.getgroups) {
  console.log(process.getgroups()); // [ 16, 21, 297 ]
}

Эта функция доступна только на платформах POSIX (т. е. не на Windows или Android).

process.getuid()

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

Метод process.getuid() возвращает числовое значение идентификатора пользователя процесса. (См. getuid(2).)

if (process.getuid) {
  console.log(`Current uid: ${process.getuid()}`);
}

Эта функция доступна только на платформах POSIX (т. е. не на Windows или Android).

process.hasUncaughtExceptionCaptureCallback()

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

Указывает, установлен ли обработчик для неперехваченных исключений с помощью process.setUncaughtExceptionCaptureCallback().

process.hrtime([time])

• time <integer[]> Результат предыдущего вызова process.hrtime()
• Возвращает: <integer[]>

Это устаревшая версия process.hrtime.bigint() до того, как bigint была введена в JavaScript.

Метод process.hrtime() возвращает текущее значение высокоточного реального времени в виде пары [seconds, nanoseconds] , где nanoseconds — оставшаяся часть реального времени, которая не может быть представлена с точностью до секунд.

time — необязательный параметр, который должен быть результатом предыдущего вызова process.hrtime() для вычисления разницы с текущим временем. Если переданный параметр не является парой Array, будет выброшено исключение TypeError. Передача пользовательского массива вместо результата предыдущего вызова process.hrtime() приведёт к неопределённому поведению.

Эти значения времени относительны к произвольному моменту времени в прошлом и не связаны с временем суток, а значит, не подвержены сдвигу часов. Основное использование — измерение производительности между интервалами:

const NS_PER_SEC = 1e9;
const time = process.hrtime();
// [ 1800216, 25 ]

setTimeout(() => {
  const diff = process.hrtime(time);
  // [ 1, 552 ]

  console.log(`Benchmark took ${diff[0] * NS_PER_SEC + diff[1]} nanoseconds`);
  // Benchmark took 1000000552 nanoseconds
}, 1000);

process.hrtime.bigint()

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

Вариант метода process.hrtime(), возвращающий текущее высокоточное реальное время в наносекундах в виде bigint.

В отличие от process.hrtime(), он не поддерживает дополнительный параметр time, так как разницу можно вычислить непосредственно вычитанием двух значений bigint.

const start = process.hrtime.bigint();
// 191051479007711n

setTimeout(() => {
  const end = process.hrtime.bigint();
  // 191052633396993n

  console.log(`Benchmark took ${end - start} nanoseconds`);
  // Benchmark took 1154389282 nanoseconds
}, 1000);

process.initgroups(user, extraGroup)

• user <string> | <number> Имя пользователя или числовой идентификатор.
• extraGroup <string> | <number> Имя группы или числовой идентификатор.

Метод process.initgroups() читает файл /etc/group и инициализирует список доступа к группам, используя все группы, членами которых является пользователь. Это привилегированная операция, которая требует, чтобы у процесса Node.js был root доступ или CAP_SETGID возможность.

Обращайтесь осторожно при понижении привилегий:

console.log(process.getgroups());         // [ 0 ]
process.initgroups('nodeuser', 1000);     // switch user
console.log(process.getgroups());         // [ 27, 30, 46, 1000, 0 ]
process.setgid(1000);                     // drop root gid
console.log(process.getgroups());         // [ 27, 30, 46, 1000 ]

Эта функция доступна только на платформах POSIX (т. е. не на Windows или Android). Эта функция недоступна в потоках Worker.

process.kill(pid[, signal])

• pid <number> Идентификатор процесса
• signal <string> | <number> Сигнал для отправки, как строка или число. По умолчанию: 'SIGTERM'.

Метод process.kill() отправляет signal процессу, идентифицированному по pid.

Имена сигналов — это строки, такие как 'SIGINT' или 'SIGHUP'. Дополнительную информацию см. в разделе Сигнальные события и kill(2).

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

Несмотря на название этой функции, process.kill(), она фактически только отправляет сигнал, подобно системному вызову kill. Отправленный сигнал может выполнить действие, отличное от завершения целевого процесса.

process.on('SIGHUP', () => {
  console.log('Got SIGHUP signal.');
});

setTimeout(() => {
  console.log('Exiting.');
  process.exit(0);
}, 100);

process.kill(process.pid, 'SIGHUP');

При получении сигнала SIGUSR1 процессом Node.js, Node.js запустит отладчик. Подробности см. в разделе Сигнальные события.

process.mainModule

• <Object>

Свойство process.mainModule предоставляет альтернативный способ получения require.main. Разница в том, что если главный модуль изменяется во время выполнения, require.main может по-прежнему ссылаться на исходный главный модуль в модулях, которые были загружены до изменения. В общем случае можно считать, что оба свойства ссылаются на один и тот же модуль.

Как и с require.main, process.mainModule будет undefined при отсутствии скрипта входа.

process.memoryUsage()

• Возвращает: <Object>
  • rss <целое>
  • heapTotal <целое>
  • heapUsed <целое>
  • external <целое>
  • arrayBuffers <целое>

Метод process.memoryUsage() возвращает объект, описывающий использование памяти процессом Node.js в байтах.

Например, код:

console.log(process.memoryUsage());

Сгенерирует:

{
  rss: 4935680,
  heapTotal: 1826816,
  heapUsed: 650472,
  external: 49879,
  arrayBuffers: 9386
}

• heapTotal и heapUsed относятся к использованию памяти V8.
• external относится к использованию памяти C++-объектов, связанных с JavaScript-объектами, управляемыми V8.
• rss, Resident Set Size, — это объем занимаемой в основной памяти (т.е. подмножество выделенной памяти) области процесса, включая все C++ и JavaScript-объекты и код.
• arrayBuffers относится к памяти, выделенной для ArrayBuffer и SharedArrayBuffer, включая все Node.js Buffer. Это также входит в значение external. При использовании Node.js как встроенной библиотеки это значение может быть 0, так как выделения памяти для ArrayBuffer могут в этом случае не отслеживаться.

При использовании потоков Worker, rss будет значением, применимым для всего процесса, в то время как другие поля будут относиться только к текущему потоку.

process.nextTick(callback[, ...args])

• callback <Функция>
• ...args <любое> Дополнительные аргументы для передачи при вызове callback

process.nextTick() добавляет callback в очередь "next tick". Эта очередь полностью обрабатывается после завершения текущей операции в стеке JavaScript и перед продолжением цикла событий. Возможно создание бесконечного цикла при рекурсивном вызове process.nextTick(). Подробнее об этом см. в руководстве по циклу событий Event Loop.

console.log('start');
process.nextTick(() => {
  console.log('nextTick callback');
});
console.log('scheduled');
// Output:
// start
// scheduled
// nextTick callback

Это важно при разработке API, чтобы предоставить пользователям возможность назначать обработчики событий *после* создания объекта, но *перед* любым вводом-выводом:

function MyThing(options) {
  this.setupOptions(options);

  process.nextTick(() => {
    this.startDoingStuff();
  });
}

const thing = new MyThing();
thing.getReadyForStuff();

// thing.startDoingStuff() gets called now, not before.

Очень важно, чтобы API было либо 100% синхронным, либо 100% асинхронным. Рассмотрим пример:

// WARNING!  DO NOT USE!  BAD UNSAFE HAZARD!
function maybeSync(arg, cb) {
  if (arg) {
    cb();
    return;
  }

  fs.stat('file', cb);
}

Это небезопасно, так как в следующем случае:

const maybeTrue = Math.random() > 0.5;

maybeSync(maybeTrue, () => {
  foo();
});

bar();

Непонятно, какой вызов foo() или bar() будет выполнен первым.

Следующий подход гораздо лучше:

function definitelyAsync(arg, cb) {
  if (arg) {
    process.nextTick(cb);
    return;
  }

  fs.stat('file', cb);
}

Когда использовать queueMicrotask() вместо process.nextTick()

API queueMicrotask() — это альтернатива process.nextTick(), которая также откладывает выполнение функции, используя ту же очередь микрозадач, что и обработчики then, catch и finally разрешенных промисов. В Node.js, каждый раз, когда обрабатывается очередь "next tick", очередь микрозадач обрабатывается сразу после нее.

Promise.resolve().then(() => console.log(2));
queueMicrotask(() => console.log(3));
process.nextTick(() => console.log(1));
// Output:
// 1
// 2
// 3

Для большинства пользовательских случаев API queueMicrotask() предоставляет переносимый и надёжный механизм отсрочки выполнения, который работает в разных средах JavaScript и должен предпочтительно использоваться вместо process.nextTick(). В простых случаях queueMicrotask() может быть прямым заменителем process.nextTick().

console.log('start');
queueMicrotask(() => {
  console.log('microtask callback');
});
console.log('scheduled');
// Output:
// start
// scheduled
// microtask callback

Существенное отличие между двумя API состоит в том, что process.nextTick() позволяет указывать дополнительные значения, которые будут переданы в качестве аргументов отложенной функции при ее вызове. Достижение того же результата с помощью queueMicrotask() требует использования либо замыкания, либо связанной функции:

function deferred(a, b) {
  console.log('microtask', a + b);
}

console.log('start');
queueMicrotask(deferred.bind(undefined, 1, 2));
console.log('scheduled');
// Output:
// start
// scheduled
// microtask 3

Есть небольшие различия в обработке ошибок, возникших в очереди "next tick" и очереди микрозадач. Ошибки, выброшенные внутри обработчика микрозадачи, должны обрабатываться внутри обработчика по возможности. Если это не так, можно использовать обработчик события process.on('uncaughtException') для захвата и обработки ошибок.

В случае сомнений, если не нужны особые возможности process.nextTick(), используйте queueMicrotask().

process.noDeprecation

• <boolean>

Свойство process.noDeprecation указывает, установлено ли флаг --no-deprecation в текущем процессе Node.js. Документацию см. в разделе 'warning' события и emitWarning() метода для получения дополнительной информации об этом флаге.

process.pid

• <целое>

Свойство process.pid возвращает PID процесса.

console.log(`This process is pid ${process.pid}`);

process.platform

• <string>

Свойство process.platform возвращает строку, идентифицирующую операционную систему, на которой работает процесс Node.js.

Возможные значения:

• 'aix'
• 'darwin'
• 'freebsd'
• 'linux'
• 'openbsd'
• 'sunos'
• 'win32'

console.log(`This platform is ${process.platform}`);

Значение 'android' также может быть возвращено, если Node.js построен для Android. Однако поддержка Android в Node.js экспериментальная.

process.ppid

• <целое>

Свойство process.ppid возвращает PID родительского процесса.

console.log(`The parent process is pid ${process.ppid}`);

process.release

• <Объект>

Свойство process.release возвращает объект Object, содержащий метаданные, связанные с текущей версией, включая URL для исходного tar-архива и tar-архива только с заголовками.

process.release содержит следующие свойства:

• name <строка> Значение, которое всегда будет 'node'.
• sourceUrl <строка> абсолютный URL, указывающий на файл .tar.gz, содержащий исходный код текущей версии.
• headersUrl<строка> абсолютный URL, указывающий на файл .tar.gz, содержащий только исходные заголовочные файлы текущей версии. Этот файл значительно меньше, чем полный исходный файл, и может использоваться для компиляции нативных дополнений Node.js.
• libUrl <строка> абсолютный URL, указывающий на файл node.lib, соответствующий архитектуре и версии текущей версии. Используется для компиляции нативных дополнений Node.js. Это свойство присутствует только в Windows-версиях Node.js и отсутствует на других платформах.
• lts <строка> строковое значение, определяющее метку LTS для данной версии. Существует только для версий LTS и undefined для всех других типов версий, включая текущие. Допустимые значения включают кодовые имена версий LTS (включая те, которые больше не поддерживаются).
  • 'Dubnium' для линейки LTS 10.x, начиная с 10.13.0.
  • 'Erbium' для линейки LTS 12.x, начиная с 12.13.0.
  Для других кодовых имён LTS см. Архив изменений Node.js

{
  name: 'node',
  lts: 'Erbium',
  sourceUrl: 'https://nodejs.org/download/release/v12.18.1/node-v12.18.1.tar.gz',
  headersUrl: 'https://nodejs.org/download/release/v12.18.1/node-v12.18.1-headers.tar.gz',
  libUrl: 'https://nodejs.org/download/release/v12.18.1/win-x64/node.lib'
}

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

process.report

• <Объект>

process.report — это объект, методы которого используются для создания диагностических отчетов для текущего процесса. Дополнительная документация доступна в документации отчетов.

process.report.compact

• <булево>

Создание отчетов в компактном формате, в формате JSON одной строки, более удобном для систем обработки логов, чем стандартный многострочный формат, предназначенный для чтения человеком.

console.log(`Reports are compact? ${process.report.compact}`);

process.report.directory

• <строка>

Директория, в которую записывается отчет. По умолчанию пустая строка, что означает запись отчетов в текущий рабочий каталог процесса Node.js.

console.log(`Report directory is ${process.report.directory}`);

process.report.filename

• <строка>

Имя файла, в который записывается отчет. Если установлено в пустую строку, имя выходного файла будет содержать метку времени, PID и порядковый номер. По умолчанию пустая строка.

console.log(`Report filename is ${process.report.filename}`);

process.report.getReport([err])

• err <Ошибка> Пользовательская ошибка, используемая для отчёта о стеке JavaScript.
• Возвращает: <Объект>

Возвращает объект JavaScript, представляющий диагностический отчет о работающем процессе. Трассировка стека JavaScript отчета взята из err, если она присутствует.

const data = process.report.getReport();
console.log(data.header.nodejsVersion);

// Similar to process.report.writeReport()
const fs = require('fs');
fs.writeFileSync(util.inspect(data), 'my-report.log', 'utf8');

Дополнительная документация доступна в документации отчетов.

process.report.reportOnFatalError

• <булево>

Если true, генерируется диагностический отчет при возникновении критических ошибок, таких как ошибки недостатка памяти или неудачные утверждения C++.

console.log(`Report on fatal error: ${process.report.reportOnFatalError}`);

process.report.reportOnSignal

• <булево>

Если true, генерируется диагностический отчет при получении процессом сигнала, указанного в process.report.signal.

console.log(`Report on signal: ${process.report.reportOnSignal}`);

process.report.reportOnUncaughtException

• <булево>

Если true, генерируется диагностический отчет при возникновении необработанного исключения.

console.log(`Report on exception: ${process.report.reportOnUncaughtException}`);

process.report.signal

• <строка>

Сигнал, используемый для запуска создания диагностического отчета. По умолчанию 'SIGUSR2'.

console.log(`Report signal: ${process.report.signal}`);

process.report.writeReport([filename][, err])

• filename <строка> Имя файла, в который записывается отчет. Должно быть относительным путем, который будет добавлен к каталогу, указанному в process.report.directory, или текущему рабочему каталогу процесса Node.js, если он не указан.

• err <Ошибка> Пользовательская ошибка, используемая для отчёта о стеке JavaScript.

• Возвращает: <строка> Возвращает имя сгенерированного отчёта.

Записывает диагностический отчет в файл. Если filename не указан, по умолчанию имя файла включает дату, время, PID и порядковый номер. Трассировка стека JavaScript отчета взята из err, если она присутствует.

process.report.writeReport();

Дополнительная документация доступна в документации отчетов.

process.resourceUsage()

• Returns: <Объект> the resource usage for the current process. All of these values come from the uv_getrusage call which returns a uv_rusage_t struct.
  • userCPUTime <целое> maps to ru_utime computed in microseconds. It is the same value as process.cpuUsage().user.
  • systemCPUTime <целое> maps to ru_stime computed in microseconds. It is the same value as process.cpuUsage().system.
  • maxRSS <целое> maps to ru_maxrss which is the maximum resident set size used in kilobytes.
  • sharedMemorySize <целое> maps to ru_ixrss but is not supported by any platform.
  • unsharedDataSize <целое> maps to ru_idrss but is not supported by any platform.
  • unsharedStackSize <целое> maps to ru_isrss but is not supported by any platform.
  • minorPageFault <целое> maps to ru_minflt which is the number of minor page faults for the process, see this article for more details.
  • majorPageFault <целое> maps to ru_majflt which is the number of major page faults for the process, see this article for more details. This field is not supported on Windows.
  • swappedOut <целое> maps to ru_nswap but is not supported by any platform.
  • fsRead <целое> maps to ru_inblock which is the number of times the file system had to perform input.
  • fsWrite <целое> maps to ru_oublock which is the number of times the file system had to perform output.
  • ipcSent <целое> maps to ru_msgsnd but is not supported by any platform.
  • ipcReceived <целое> maps to ru_msgrcv but is not supported by any platform.
  • signalsCount <целое> maps to ru_nsignals but is not supported by any platform.
  • voluntaryContextSwitches <целое> maps to ru_nvcsw which is the number of times a CPU context switch resulted due to a process voluntarily giving up the processor before its time slice was completed (usually to await availability of a resource). This field is not supported on Windows.
  • involuntaryContextSwitches <целое> maps to ru_nivcsw which is the number of times a CPU context switch resulted due to a higher priority process becoming runnable or because the current process exceeded its time slice. This field is not supported on Windows.

console.log(process.resourceUsage());
/*
  Will output:
  {
    userCPUTime: 82872,
    systemCPUTime: 4143,
    maxRSS: 33164,
    sharedMemorySize: 0,
    unsharedDataSize: 0,
    unsharedStackSize: 0,
    minorPageFault: 2469,
    majorPageFault: 0,
    swappedOut: 0,
    fsRead: 0,
    fsWrite: 8,
    ipcSent: 0,
    ipcReceived: 0,
    signalsCount: 0,
    voluntaryContextSwitches: 79,
    involuntaryContextSwitches: 1
  }
*/

process.send(message[, sendHandle[, options]][, callback])

• message <Объект>
• sendHandle <net.Сервер> | <net.Сокет>
• options <Объект> used to parameterize the sending of certain types of handles.options supports the following properties:
  • keepOpen <логическое> A value that can be used when passing instances of net.Socket. When true, the socket is kept open in the sending process. Default: false.
• callback <Функция>
• Returns: <логическое>

If Node.js is spawned with an IPC channel, the process.send() method can be used to send messages to the parent process. Messages will be received as a 'message' event on the parent's ChildProcess object.

If Node.js was not spawned with an IPC channel, process.send will be undefined.

The message goes through serialization and parsing. The resulting message might not be the same as what is originally sent.

process.setegid(id)

• id <строка> | <число> A group name or ID

The process.setegid() method sets the effective group identity of the process. (See setegid(2).) The id can be passed as either a numeric ID or a group name string. If a group name is specified, this method blocks while resolving the associated a numeric ID.

if (process.getegid && process.setegid) {
  console.log(`Current gid: ${process.getegid()}`);
  try {
    process.setegid(501);
    console.log(`New gid: ${process.getegid()}`);
  } catch (err) {
    console.log(`Failed to set gid: ${err}`);
  }
}

This function is only available on POSIX platforms (i.e. not Windows or Android). This feature is not available in Worker threads.

process.seteuid(id)

• id <строка> | <число> A user name or ID

The process.seteuid() method sets the effective user identity of the process. (See seteuid(2).) The id can be passed as either a numeric ID or a username string. If a username is specified, the method blocks while resolving the associated numeric ID.

if (process.geteuid && process.seteuid) {
  console.log(`Current uid: ${process.geteuid()}`);
  try {
    process.seteuid(501);
    console.log(`New uid: ${process.geteuid()}`);
  } catch (err) {
    console.log(`Failed to set uid: ${err}`);
  }
}

This function is only available on POSIX platforms (i.e. not Windows or Android). This feature is not available in Worker threads.

process.setgid(id)

• id <строка> | <число> The group name or ID

The process.setgid() method sets the group identity of the process. (See setgid(2).) The id can be passed as either a numeric ID or a group name string. If a group name is specified, this method blocks while resolving the associated numeric ID.

if (process.getgid && process.setgid) {
  console.log(`Current gid: ${process.getgid()}`);
  try {
    process.setgid(501);
    console.log(`New gid: ${process.getgid()}`);
  } catch (err) {
    console.log(`Failed to set gid: ${err}`);
  }
}

This function is only available on POSIX platforms (i.e. not Windows or Android). This feature is not available in Worker threads.

process.setgroups(groups)

• groups <массив целых>

The process.setgroups() method sets the supplementary group IDs for the Node.js process. This is a privileged operation that requires the Node.js process to have root or the CAP_SETGID capability.

The groups array can contain numeric group IDs, group names, or both.

if (process.getgroups && process.setgroups) {
  try {
    process.setgroups([501]);
    console.log(process.getgroups()); // new groups
  } catch (err) {
    console.log(`Failed to set groups: ${err}`);
  }
}

This function is only available on POSIX platforms (i.e. not Windows or Android). This feature is not available in Worker threads.

process.setuid(id)

• id <integer> | <string>

Метод process.setuid(id) устанавливает идентификатор пользователя процесса. (См. setuid(2).) id может быть передан как числовой идентификатор или строковое имя пользователя. Если указано имя пользователя, метод блокируется до разрешения соответствующего числового идентификатора.

if (process.getuid && process.setuid) {
  console.log(`Current uid: ${process.getuid()}`);
  try {
    process.setuid(501);
    console.log(`New uid: ${process.getuid()}`);
  } catch (err) {
    console.log(`Failed to set uid: ${err}`);
  }
}

Эта функция доступна только на платформах POSIX (т.е. не на Windows и Android). Эта функция недоступна в потоках Worker.

process.setUncaughtExceptionCaptureCallback(fn)

• fn <Function> | <null>

Функция process.setUncaughtExceptionCaptureCallback() устанавливает функцию, которая будет вызвана при возникновении непредвиденной ошибки, получив значение ошибки в качестве первого аргумента.

Если такая функция установлена, событие 'uncaughtException' не будет выведено. Если --abort-on-uncaught-exception был передан из командной строки или установлен через v8.setFlagsFromString(), процесс не прервётся. Действия, настроенные на выполнение при ошибках, такие как генерация отчётов, также будут затронуты.

Для отмены функции захвата можно использовать process.setUncaughtExceptionCaptureCallback(null). Вызов этого метода с аргументом, отличным от null, в то время как другая функция захвата установлена, вызовет ошибку.

Использование этой функции взаимоисключает использование устаревшего встроенного модуля domain.

process.stderr

• <Stream>

Свойство process.stderr возвращает поток, подключённый к stderr (дескриптор файла 2). Это net.Socket (который является потоком типа Duplex), если дескриптор файла 2 ссылается на файл, в противном случае это поток типа Writable.

process.stderr отличается от других потоков Node.js важными способами. Подробнее см. примечание о вводе-выводе процесса.

process.stderr.fd

• <number>

Это свойство относится к значению базового дескриптора файла process.stderr. Значение фиксировано на 2. В потоках Worker это поле отсутствует.

process.stdin

• <Stream>

Свойство process.stdin возвращает поток, подключённый к stdin (дескриптор файла 0). Это net.Socket (который является потоком типа Duplex), если дескриптор файла 0 ссылается на файл, в противном случае это поток типа Readable.

Подробности о чтении из stdin см. в readable.read().

Как поток типа Duplex, process.stdin также может быть использован в "старом" режиме, совместимом со скриптами, написанными для Node.js до версии 0.10. Подробнее см. в Совместимости потоков.

В режиме "старых" потоков поток stdin по умолчанию приостановлен, поэтому необходимо вызвать process.stdin.resume() для чтения из него. Обратите также внимание, что вызов process.stdin.resume() сам по себе переключит поток в "старый" режим.

process.stdin.fd

• <number>

Это свойство относится к значению базового дескриптора файла process.stdin. Значение фиксировано на 0. В потоках Worker это поле отсутствует.

process.stdout

• <Stream>

Свойство process.stdout возвращает поток, подключённый к stdout (дескриптор файла 1). Это net.Socket (который является потоком типа Duplex), если дескриптор файла 1 ссылается на файл, в противном случае это поток типа Writable.

Например, для копирования process.stdin в process.stdout:

process.stdin.pipe(process.stdout);

process.stdout отличается от других потоков Node.js важными способами. Подробнее см. примечание о вводе-выводе процесса.

process.stdout.fd

• <number>

Это свойство относится к значению базового дескриптора файла process.stdout. Значение фиксировано на 1. В потоках Worker это поле отсутствует.

Примечание о вводе-выводе процесса

process.stdout и process.stderr отличаются от других потоков Node.js важными способами:

1. Они используются внутренне функциями console.log() и console.error() соответственно.
2. Записи могут быть синхронными в зависимости от того, с чем соединён поток, и от того, Windows или POSIX система:
   • Файлы: синхронно на Windows и POSIX
   • TTY (терминалы): асинхронно на Windows, синхронно на POSIX
   • Каналы (и сокеты): синхронно на Windows, асинхронно на POSIX

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

Синхронные записи предотвращают проблемы, такие как неожиданное переплетение вывода с использованием console.log() или console.error(), или его полное отсутствие, если process.exit() вызывается до завершения асинхронной записи. См. process.exit() для получения дополнительной информации.

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

Чтобы проверить, подключён ли поток к контексту TTY, проверьте свойство isTTY.

Например:

$ node -p "Boolean(process.stdin.isTTY)"
true
$ echo "foo" | node -p "Boolean(process.stdin.isTTY)"
false
$ node -p "Boolean(process.stdout.isTTY)"
true
$ node -p "Boolean(process.stdout.isTTY)" | cat
false

См. документацию по TTY для получения дополнительной информации.

process.throwDeprecation

• <boolean>

Начальное значение process.throwDeprecation указывает, установлен ли флаг --throw-deprecation в текущем процессе Node.js. process.throwDeprecation изменяемое, поэтому предупреждения об устаревании могут привести к ошибкам во время выполнения. Смотрите документацию для события 'warning' и метода emitWarning() для получения дополнительной информации.

$ node --throw-deprecation -p "process.throwDeprecation"
true
$ node -p "process.throwDeprecation"
undefined
$ node
> process.emitWarning('test', 'DeprecationWarning');
undefined
> (node:26598) DeprecationWarning: test
> process.throwDeprecation = true;
true
> process.emitWarning('test', 'DeprecationWarning');
Thrown:
[DeprecationWarning: test] { name: 'DeprecationWarning' }

process.title

• <string>

Свойство process.title возвращает текущее название процесса (т.е. возвращает текущее значение ps). Присвоение нового значения process.title изменяет текущее значение ps.

При присвоении нового значения разные платформы будут накладывать разные ограничения на максимальную длину названия. Обычно эти ограничения довольно жёсткие. Например, в Linux и macOS process.title ограничено размером имени исполняемого файла плюс длиной аргументов командной строки, поскольку установка process.title перезаписывает память argv процесса. Node.js v0.8 позволял более длинные названия процессов, перезаписывая также память environ, но это потенциально было небезопасно и вызывало путаницу в некоторых (довольно редких) случаях.

Присвоение значения process.title может не привести к точному отображению в приложениях диспетчера процессов, таких как macOS Activity Monitor или Windows Services Manager.

process.traceDeprecation

• <boolean>

Свойство process.traceDeprecation указывает, установлен ли флаг --trace-deprecation в текущем процессе Node.js. Смотрите документацию для события 'warning' и метода emitWarning() для получения дополнительной информации о поведении этого флага.

process.umask()

process.umask() возвращает маску создания режима файла процесса Node.js. Потомки процессов наследуют маску от родительского процесса.

process.umask(mask)

• mask <строка> | <целое число>

process.umask(mask) устанавливает маску создания режима файла процесса Node.js. Потомки процессов наследуют маску от родительского процесса. Возвращает предыдущую маску.

const newmask = 0o022;
const oldmask = process.umask(newmask);
console.log(
  `Changed umask from ${oldmask.toString(8)} to ${newmask.toString(8)}`
);

В потоках Worker process.umask(mask) будет выбрасывать исключение.

process.uptime()

• Возвращает: <число>

Метод process.uptime() возвращает количество секунд, в течение которых текущий процесс Node.js работает.

Значение возврата включает дробные доли секунды. Используйте Math.floor() для получения целых секунд.

process.version

• <строка>

Свойство process.version содержит строку версии Node.js.

console.log(`Version: ${process.version}`);
// Version: v14.8.0

Чтобы получить строку версии без префикса v, используйте process.versions.node.

process.versions

• <Объект>

Свойство process.versions возвращает объект, перечисляющий строки версий Node.js и его зависимостей. process.versions.modules указывает текущую ABI-версию, которая увеличивается всякий раз, когда изменяется API C++. Node.js откажется от загрузки модулей, скомпилированных для другой версии модульного ABI.

console.log(process.versions);

Сгенерирует объект, аналогичный:

{ node: '11.13.0',
  v8: '7.0.276.38-node.18',
  uv: '1.27.0',
  zlib: '1.2.11',
  brotli: '1.0.7',
  ares: '1.15.0',
  modules: '67',
  nghttp2: '1.34.0',
  napi: '4',
  llhttp: '1.1.1',
  openssl: '1.1.1b',
  cldr: '34.0',
  icu: '63.1',
  tz: '2018e',
  unicode: '11.0' }

Коды завершения

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

• 1 Необработанное фатальное исключение: Произошло необработанное исключение, и оно не было обработано областью или обработчиком событий 'uncaughtException'.
• 2: Неиспользуемый (зарезервирован Bash для неправильного использования встроенных команд)
• 3 Внутренняя ошибка синтаксического анализа JavaScript: Внутренний для Node.js код JavaScript вызвал синтаксическую ошибку. Это крайне редко, и, как правило, это может произойти только во время разработки самого Node.js.
• 4 Внутренняя ошибка вычисления JavaScript: Внутренний для Node.js код JavaScript не смог вернуть значение функции при вычислении. Это крайне редко, и, как правило, это может произойти только во время разработки самого Node.js.
• 5 Фатальная ошибка: В V8 произошла фатальная непреодолимая ошибка. Обычно сообщение будет выведено в stderr с префиксом FATAL ERROR.
• 6 Обработчик внутренних исключений не является функцией: Произошло необработанное исключение, но внутренняя функция-обработчик фатальных исключений каким-то образом была установлена ​​как не функция и не могла быть вызвана.
• 7 Ошибка выполнения внутреннего обработчика исключений: Произошло необработанное исключение, и сама внутренняя функция-обработчик фатальных исключений выбросила ошибку при попытке обработать его. Это может произойти, например, если 'uncaughtException' или domain.on('error') обработчик выбросит ошибку.
• 8: Неиспользуемый. В предыдущих версиях Node.js код завершения 8 иногда указывал на необработанное исключение.
• 9 Неверный аргумент: Был указан неизвестный параметр или параметр, требующий значения, был предоставлен без значения.
• 10 Внутренняя ошибка выполнения JavaScript: Внутренний для Node.js код JavaScript выбросил ошибку при вызове функции запуска. Это крайне редко, и, как правило, это может произойти только во время разработки самого Node.js.
• 12 Неверный аргумент отладки: Были установлены параметры --inspect и/или --inspect-brk, но выбранный номер порта был неверным или недоступным.
• 13 Незавершенный асинхронный оператор await в верхнем уровне: await был использован вне функции в верхнем уровне кода, но переданный Promise никогда не разрешился.
• >128 Выход по сигналам: Если Node.js получает фатальный сигнал, такой как SIGKILL или SIGHUP, тогда его код выхода будет 128 плюс значение кода сигнала. Это стандартная практика POSIX, поскольку коды выхода определены как 7-битные целые числа, а выход по сигналам устанавливают старший бит, а затем содержат значение кода сигнала. Например, сигнал SIGABRT имеет значение 6, поэтому ожидаемый код выхода будет 128 + 6, или 134.