События процесса

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

Событие: 'beforeExit'

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

Функция обратного вызова слушателя вызывается со значением process.exitCode, переданным в качестве единственного аргумента.

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

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

import process from 'node:process';

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

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

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-каналом (см. документацию по Child Process и Cluster), событие 'disconnect' будет сгенерировано при закрытии IPC-канала.

Событие: 'exit'

• code <integer>

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

• Явный вызов метода process.exit();
• Цикл событий Node.js больше не содержит работы для выполнения.

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

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

import process from 'node:process';

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

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

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

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

import process from 'node:process';

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

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

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

Событие: 'message'

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

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

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

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

Событие: 'multipleResolves'

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

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

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

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

Из-за ненадежности этого события в случаях, подобных приведенному выше примеру с Promise.race(), оно было объявлено устаревшим.

import process from 'node:process';

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

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

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> Промис, обработанный с опозданием.

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

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

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

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

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

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

import process from 'node:process';

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

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

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

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

Событие: 'workerMessage'

• value <any> Значение, переданное с помощью postMessageToThread().
• source <number> Идентификатор передающего потока worker или 0 для главного потока.

Событие 'workerMessage' генерируется для любого входящего сообщения, отправленного другой стороной с помощью postMessageToThread().

Событие: 'uncaughtException'

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

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

import process from 'node:process';
import fs from 'node:fs';

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

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

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

const process = require('node:process');
const fs = require('node:fs');

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

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 <Error> Необработанное исключение.
• origin <string> Указывает, возникло ли исключение из-за необработанного отклонения или из-за синхронных ошибок. Может иметь значение 'uncaughtException' или 'unhandledRejection'. Последнее используется, когда исключение возникает в асинхронном контексте на основе Promise (или если Promise отклонен), флаг --unhandled-rejections установлен в strict или throw (что является значением по умолчанию) и отклонение не обработано, либо когда отклонение происходит на этапе статической загрузки модулей ES для точки входа командной строки.

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

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

import process from 'node:process';

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

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

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

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> | <any> Объект, с которым промис был отклонен (обычно объект Error).
• promise <Promise> Отклоненный промис.

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

import process from 'node:process';

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()`

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

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':

import process from 'node:process';

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

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

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'. Чтобы устранить такие сбои, к resource.loaded можно прикрепить холостой обработчик .catch(() => { }), что предотвратит генерацию события 'unhandledRejection'.

Если событие 'unhandledRejection' сгенерировано, но не обработано, оно вызовет необработанное исключение. Это, а также другое поведение событий 'unhandledRejection', можно изменить с помощью флага --unhandled-rejections.

Событие: 'warning'

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

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

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

import process from 'node:process';

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
});

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

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. В настоящее время невозможно подавить определенные типы предупреждений, кроме предупреждений об устаревании. Чтобы подавить предупреждения об устаревании, ознакомьтесь с флагом --no-deprecation.

Следующий пример иллюстрирует предупреждение, которое выводится в 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 copy

Напротив, в следующем примере отключается стандартный вывод предупреждений и добавляется пользовательский обработчик для события '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! copy

Параметр командной строки --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' — указывает на то, что в функцию setTimeout() или setInterval() передано числовое значение, которое не помещается в 32-битное знаковое целое число.
• 'UnsupportedWarning' — указывает на использование неподдерживаемой опции или возможности, которая будет проигнорирована, а не обработана как ошибка. Одним из примеров является использование сообщения о статусе HTTP-ответа при использовании API совместимости с HTTP/2.

Событие: 'worker'

• worker <Worker> Созданный объект <Worker>.

Событие 'worker' генерируется после создания нового потока <Worker>.

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

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

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

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

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

import process from 'node:process';

// 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);

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

// 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 для запуска отладчика. Слушатель установить можно, но это может помешать работе отладчика.
• 'SIGTERM' и 'SIGINT' на платформах, отличных от Windows, имеют обработчики по умолчанию, которые сбрасывают режим терминала перед завершением с кодом 128 + signal number. Если для одного из этих сигналов установлен слушатель, его поведение по умолчанию будет удалено (Node.js больше не будет завершать работу).
• 'SIGPIPE' игнорируется по умолчанию. Для него можно установить слушатель.
• 'SIGHUP' генерируется в Windows при закрытии окна консоли, а на других платформах — при различных аналогичных условиях. См. signal(7). Для него можно установить слушатель, однако примерно через 10 секунд Node.js будет безусловно завершен Windows. На платформах, отличных от Windows, поведением по умолчанию для SIGHUP является завершение Node.js, но после установки слушателя поведение по умолчанию будет отключено.
• 'SIGTERM' не поддерживается в Windows, его можно прослушивать.
• 'SIGINT' из терминала поддерживается на всех платформах и обычно может быть сгенерирован с помощью Ctrl+C (хотя это можно настроить). Он не генерируется, если включен необработанный режим терминала и используется комбинация Ctrl+C.
• 'SIGBREAK' доставляется в Windows при нажатии Ctrl+Break. На платформах, отличных от Windows, его можно прослушивать, но нет способа отправить или сгенерировать его.
• 'SIGWINCH' доставляется при изменении размера консоли. В Windows это происходит только при записи в консоль при перемещении курсора или при использовании читаемого tty в режиме raw.
• Для '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, будут содержать символы подчеркивания вместо неначальных дефисов:

import { allowedNodeEnvironmentFlags } from 'node:process';

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

const { allowedNodeEnvironmentFlags } = require('node: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', 'loong64', 'mips', 'mipsel', 'ppc', 'ppc64', 'riscv64', 's390', 's390x' и 'x64'.

import { arch } from 'node:process';

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

const { arch } = require('node:process');

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

process.argv

• <string[]>

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

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

import { argv } from 'node:process';

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

const { argv } = require('node:process');

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

Запуск процесса Node.js следующим образом:

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

Сгенерирует следующий вывод:

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

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' copy

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 не существует).

import { chdir, cwd } from 'node:process';

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

const { chdir, cwd } = require('node:process');

console.log(`Starting directory: ${cwd()}`);
try {
  chdir('/tmp');
  console.log(`New directory: ${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_openssl: 'true',
     node_shared_openssl: 'false',
     strict_aliasing: 'true',
     target_arch: 'x64',
     v8_use_snapshot: 1
   }
} copy

process.connected

• <boolean>

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

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

process.constrainedMemory()

• <number>

Возвращает объем памяти, доступный процессу (в байтах), на основе ограничений, налагаемых ОС. Если такого ограничения нет или оно неизвестно, возвращается 0.

Дополнительную информацию см. в uv_get_constrained_memory.

process.availableMemory()

• <number>

Возвращает объем свободной памяти, которая всё еще доступна процессу (в байтах).

Дополнительную информацию см. в uv_get_available_memory.

process.cpuUsage([previousValue])

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

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

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

import { cpuUsage } from 'node:process';

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

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

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

const { cpuUsage } = require('node:process');

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

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

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

process.cwd()

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

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

import { cwd } from 'node:process';

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

const { cwd } = require('node:process');

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

process.debugPort

• <number>

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

import process from 'node:process';

process.debugPort = 5858;

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

process.debugPort = 5858;

process.disconnect()

Если процесс Node.js создан с IPC-каналом (см. документацию по Child Process и Cluster), метод process.disconnect() закроет IPC-канал к родительскому процессу, позволяя дочернему процессу корректно завершиться, если его работу больше не поддерживают другие соединения.

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

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

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

• module <Object>
• filename <string>
• 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. В этом примере предполагается, что константа доступна.

import { dlopen } from 'node:process';
import { constants } from 'node:os';
import { fileURLToPath } from 'node:url';

const module = { exports: {} };
dlopen(module, fileURLToPath(new URL('local.node', import.meta.url)),
       constants.dlopen.RTLD_NOW);
module.exports.foo();

const { dlopen } = require('node:process');
const { constants } = require('node:os');
const { join } = require('node:path');

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

process.emitWarning(warning[, options])

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

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

import { emitWarning } from 'node:process';

// Emit a warning with a code and additional detail.
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

const { emitWarning } = require('node:process');

// Emit a warning with a code and additional detail.
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'.

import process from 'node:process';

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'
});

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

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 <string> | <Error> Предупреждение, которое необходимо сгенерировать.
• type <string> Если warning является String, type указывает имя для типа генерируемого предупреждения. По умолчанию: 'Warning'.
• code <string> Уникальный идентификатор для экземпляра генерируемого предупреждения.
• ctor <Function> Если warning является String, ctor является необязательной функцией, используемой для ограничения создаваемого стека вызовов. По умолчанию: process.emitWarning.

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

import { emitWarning } from 'node:process';

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

const { emitWarning } = require('node:process');

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

import { emitWarning } from 'node:process';

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

const { emitWarning } = require('node:process');

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

import { emitWarning } from 'node:process';

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

const { emitWarning } = require('node:process');

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

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

import process from 'node:process';

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

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

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 будут проигнорированы):

import { emitWarning } from 'node:process';

// 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';

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

const { emitWarning } = require('node:process');

// 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';

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

Исключение TypeError возникает, если значение warning отличается от строки или объекта Error.

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

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

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

Предотвращение дублирования предупреждений

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

import { emitWarning } from 'node:process';

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

const { emitWarning } = require('node:process');

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

process.env

• <Object>

Свойство 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'
} copy

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

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

Тогда как следующий — будет:

import { env } from 'node:process';

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

const { env } = require('node:process');

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

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

import { env } from 'node:process';

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

const { env } = require('node:process');

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

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

import { env } from 'node:process';

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

const { env } = require('node:process');

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

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

import { env } from 'node:process';

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

const { env } = require('node:process');

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

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

process.execArgv

• <string[]>

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

node --icu-data-dir=./foo --require ./bar.js script.js --version copy

Дает в результате process.execArgv:

["--icu-data-dir=./foo", "--require", "./bar.js"] copy

И process.argv:

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

Подробное описание поведения рабочих потоков с этим свойством см. в конструкторе Worker.

process.execPath

• <string>

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

'/usr/local/bin/node' copy

process.exit([code])

• code <integer> | <string> | <null> | <undefined> Код завершения. Для типа string разрешены только целочисленные строки (например, '1'). По умолчанию: 0.

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

Чтобы завершить процесс с кодом «ошибка»:

import { exit } from 'node:process';

exit(1);

const { exit } = require('node:process');

exit(1);

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

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

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

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

import { exit } from 'node:process';

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

const { exit } = require('node:process');

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

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

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

import process from 'node:process';

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

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

// 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> | <string> | <null> | <undefined> Код завершения. Для типа string разрешены только целочисленные строки (например, '1'). По умолчанию: undefined.

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

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

process.features.cached_builtins

• <boolean>

Логическое значение, равное true, если текущая сборка Node.js кэширует встроенные модули.

process.features.debug

• <boolean>

Логическое значение, равное true, если текущая сборка Node.js является отладочной сборкой.

process.features.inspector

• <boolean>

Логическое значение, равное true, если текущая сборка Node.js включает инспектор.

process.features.ipv6

• <boolean>

Логическое значение, равное true, если текущая сборка Node.js включает поддержку IPv6.

process.features.require_module

• <boolean>

Логическое значение, равное true, если текущая сборка Node.js поддерживает загрузку модулей ECMAScript с помощью require().

process.features.tls

• <boolean>

Логическое значение, равное true, если текущая сборка Node.js включает поддержку TLS.

process.features.tls_alpn

• <boolean>

Логическое значение, равное true, если текущая сборка Node.js включает поддержку ALPN в TLS.

process.features.tls_ocsp

• <boolean>

Логическое значение, равное true, если текущая сборка Node.js включает поддержку OCSP в TLS.

process.features.tls_sni

• <boolean>

Логическое значение, равное true, если текущая сборка Node.js включает поддержку SNI в TLS.

process.features.uv

• <boolean>

Логическое значение, равное true, если текущая сборка Node.js включает поддержку libuv. Поскольку в настоящее время невозможно собрать Node.js без libuv, это значение всегда равно true.

process.getActiveResourcesInfo()

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

Метод process.getActiveResourcesInfo() возвращает массив строк, содержащих типы активных ресурсов, которые в данный момент поддерживают работу цикла событий.

import { getActiveResourcesInfo } from 'node:process';
import { setTimeout } from 'node:timers';

console.log('Before:', getActiveResourcesInfo());
setTimeout(() => {}, 1000);
console.log('After:', getActiveResourcesInfo());
// Prints:
//   Before: [ 'CloseReq', 'TTYWrap', 'TTYWrap', 'TTYWrap' ]
//   After: [ 'CloseReq', 'TTYWrap', 'TTYWrap', 'TTYWrap', 'Timeout' ]

const { getActiveResourcesInfo } = require('node:process');
const { setTimeout } = require('node:timers');

console.log('Before:', getActiveResourcesInfo());
setTimeout(() => {}, 1000);
console.log('After:', getActiveResourcesInfo());
// Prints:
//   Before: [ 'TTYWrap', 'TTYWrap', 'TTYWrap' ]
//   After: [ 'TTYWrap', 'TTYWrap', 'TTYWrap', 'Timeout' ]

process.getBuiltinModule(id)

• id <string> Идентификатор запрашиваемого встроенного модуля.
• Возвращает: <Object> | <undefined>

process.getBuiltinModule(id) предоставляет способ загрузки встроенных модулей с помощью глобально доступной функции. Модули ES, которым требуется поддержка других сред выполнения, могут использовать ее для условной загрузки встроенного модуля Node.js при запуске в Node.js, не сталкиваясь с ошибкой разрешения модулей, которая может быть вызвана import в среде, отличной от Node.js, и без необходимости использовать динамический import(), который либо делает модуль асинхронным, либо превращает синхронный API в асинхронный.

if (globalThis.process?.getBuiltinModule) {
  // Run in Node.js, use the Node.js fs module.
  const fs = globalThis.process.getBuiltinModule('fs');
  // If `require()` is needed to load user-modules, use createRequire()
  const module = globalThis.process.getBuiltinModule('module');
  const require = module.createRequire(import.meta.url);
  const foo = require('foo');
} copy

Если id указывает на встроенный модуль, доступный в текущем процессе Node.js, метод process.getBuiltinModule(id) возвращает соответствующий встроенный модуль. Если id не соответствует ни одному встроенному модулю, возвращается undefined.

process.getBuiltinModule(id) принимает идентификаторы встроенных модулей, распознаваемые module.isBuiltin(id). Некоторые встроенные модули должны загружаться с префиксом node:, см. встроенные модули с обязательным префиксом node:. Ссылки, возвращаемые process.getBuiltinModule(id), всегда указывают на встроенный модуль, соответствующий id, даже если пользователи модифицируют require.cache таким образом, что require(id) возвращает что-то другое.

process.getegid()

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

import process from 'node:process';

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

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

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

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

process.geteuid()

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

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

import process from 'node:process';

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

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

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

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

process.getgid()

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

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

import process from 'node:process';

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

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

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

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

process.getgroups()

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

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

import process from 'node:process';

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

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

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

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

process.getuid()

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

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

import process from 'node:process';

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

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

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() до того, как в JavaScript был представлен bigint.

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

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

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

import { hrtime } from 'node:process';

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

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

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

const { hrtime } = require('node:process');

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

setTimeout(() => {
  const diff = 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, возвращающая текущее реальное время высокого разрешения в наносекундах в виде bigint.

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

import { hrtime } from 'node:process';

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

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

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

const { hrtime } = require('node:process');

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

setTimeout(() => {
  const end = 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.

Будьте осторожны при сбросе привилегий:

import { getgroups, initgroups, setgid } from 'node:process';

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

const { getgroups, initgroups, setgid } = require('node:process');

console.log(getgroups());         // [ 0 ]
initgroups('nodeuser', 1000);     // switch user
console.log(getgroups());         // [ 27, 30, 46, 1000, 0 ]
setgid(1000);                     // drop root gid
console.log(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 возникнет ошибка, если pid используется для завершения группы процессов.

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

import process, { kill } from 'node:process';

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

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

kill(process.pid, 'SIGHUP');

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

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

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

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

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

process.loadEnvFile(path)

• path <string> | <URL> | <Buffer> | <undefined>. По умолчанию: './.env'

Загружает файл .env в process.env. Использование NODE_OPTIONS в файле .env не окажет никакого влияния на Node.js.

const { loadEnvFile } = require('node:process');
loadEnvFile();

import { loadEnvFile } from 'node:process';
loadEnvFile();

process.mainModule

• <Object>

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

Как и в случае с require.main, process.mainModule будет иметь значение undefined, если входной скрипт отсутствует.

process.memoryUsage()

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

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

import { memoryUsage } from 'node:process';

console.log(memoryUsage());
// Prints:
// {
//  rss: 4935680,
//  heapTotal: 1826816,
//  heapUsed: 650472,
//  external: 49879,
//  arrayBuffers: 9386
// }

const { memoryUsage } = require('node:process');

console.log(memoryUsage());
// Prints:
// {
//  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, включая все Buffer в Node.js. Это также включено в значение external. Когда Node.js используется в качестве встроенной библиотеки, это значение может быть равно 0, поскольку выделения памяти для ArrayBuffer в этом случае могут не отслеживаться.

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

Метод process.memoryUsage() выполняет итерацию по каждой странице для сбора информации об использовании памяти, что может работать медленно в зависимости от выделений памяти программы.

process.memoryUsage.rss()

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

Метод process.memoryUsage.rss() возвращает целое число, представляющее размер резидентного набора (Resident Set Size, RSS) в байтах.

Размер резидентного набора — это объем пространства, занимаемый процессом в оперативной памяти (являющийся подмножеством общего объема выделенной памяти), включая весь код и все объекты C++ и JavaScript.

Это то же значение, что и свойство rss, предоставляемое process.memoryUsage(), однако метод process.memoryUsage.rss() работает быстрее.

import { memoryUsage } from 'node:process';

console.log(memoryUsage.rss());
// 35655680

const { memoryUsage } = require('node:process');

console.log(memoryUsage.rss());
// 35655680

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

• callback <Function>
• ...args <any> Дополнительные аргументы, передаваемые при вызове callback

process.nextTick() добавляет callback в «очередь следующего тика» (next tick queue). Эта очередь полностью очищается после завершения текущей операции в стеке JavaScript и до того, как цикл событий продолжит работу. При рекурсивном вызове process.nextTick() можно создать бесконечный цикл. Дополнительные сведения см. в руководстве по циклу событий.

import { nextTick } from 'node:process';

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

const { nextTick } = require('node:process');

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

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

import { nextTick } from 'node:process';

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

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

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

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

const { nextTick } = require('node:process');

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

  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);
} copy

Такой API опасен, поскольку в следующем случае:

const maybeTrue = Math.random() > 0.5;

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

bar(); copy

Неясно, что будет вызвано раньше: foo() или bar().

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

import { nextTick } from 'node:process';

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

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

const { nextTick } = require('node:process');

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

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

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

API queueMicrotask() представляет собой альтернативу process.nextTick(), которая вместо «очереди следующего тика» откладывает выполнение функции с помощью той же очереди микрозадач, которая используется для выполнения обработчиков then, catch и finally разрешённых промисов.

В Node.js каждый раз при очистке «очереди следующего тика» сразу после неё очищается очередь микрозадач.

Таким образом, в модулях CJS колбэки process.nextTick() всегда выполняются раньше колбэков queueMicrotask(). Однако, поскольку модули ESM обрабатываются уже как часть очереди микрозадач, в них колбэки queueMicrotask() всегда выполняются раньше process.nextTick(), так как Node.js уже находится в процессе очистки очереди микрозадач.

import { nextTick } from 'node:process';

Promise.resolve().then(() => console.log('resolve'));
queueMicrotask(() => console.log('microtask'));
nextTick(() => console.log('nextTick'));
// Output:
// resolve
// microtask
// nextTick

const { nextTick } = require('node:process');

Promise.resolve().then(() => console.log('resolve'));
queueMicrotask(() => console.log('microtask'));
nextTick(() => console.log('nextTick'));
// Output:
// nextTick
// resolve
// microtask

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

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

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

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 copy

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

В случае сомнений, если не требуются специфические возможности process.nextTick(), используйте queueMicrotask().

process.noDeprecation

• <boolean>

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

process.permission

• <Object>

Этот API доступен с помощью флага --experimental-permission.

process.permission — это объект, методы которого используются для управления разрешениями для текущего процесса. Дополнительная документация доступна в разделе Модель разрешений (Permission Model).

process.permission.has(scope[, reference])

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

Проверяет, имеет ли процесс доступ к заданной области (scope) и ресурсу (reference). Если ресурс не указан, предполагается глобальная область, например process.permission.has('fs.read') проверит, имеет ли процесс ВСЕ разрешения на чтение из файловой системы.

Значение reference зависит от предоставленной области (scope). Например, когда областью является файловая система, reference означает файлы и папки.

Доступные области:

• fs — вся файловая система
• fs.read — операции чтения файловой системы
• fs.write — операции записи файловой системы
• child — операции создания дочерних процессов
• worker — операция создания рабочих потоков (worker threads)

// Check if the process has permission to read the README file
process.permission.has('fs.read', './README.md');
// Check if the process has read permission operations
process.permission.has('fs.read'); copy

process.pid

• <integer>

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

import { pid } from 'node:process';

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

const { pid } = require('node:process');

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

process.platform

• <string>

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

В настоящее время возможными значениями являются:

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

import { platform } from 'node:process';

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

const { platform } = require('node:process');

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

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

process.ppid

• <integer>

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

import { ppid } from 'node:process';

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

const { ppid } = require('node:process');

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

process.release

• <Object>

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

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

• name <string> Значение, которое всегда будет равно 'node'.
• sourceUrl <string> абсолютный URL, указывающий на файл .tar.gz, содержащий исходный код текущего релиза.
• headersUrl<string> абсолютный URL, указывающий на файл .tar.gz, содержащий только заголовочные файлы текущего релиза. Этот файл значительно меньше полного файла с исходным кодом и может использоваться для компиляции нативных аддонов Node.js.
• libUrl <string> | <undefined> абсолютный URL, указывающий на файл node.lib, соответствующий архитектуре и версии текущего релиза. Этот файл используется для компиляции нативных аддонов Node.js. Это свойство присутствует только в сборках Node.js для Windows и отсутствует на всех остальных платформах.
• lts <string> | <undefined> строковая метка, определяющая метку LTS для этого релиза. Это свойство существует только для LTS-релизов и имеет значение undefined для всех остальных типов релизов, включая релизы Current. Допустимые значения включают кодовые имена LTS-релизов (в том числе те, поддержка которых уже прекращена).
  • 'Fermium' для линейки 14.x LTS начиная с 14.15.0.
  • 'Gallium' для линейки 16.x LTS начиная с 16.13.0.
  • 'Hydrogen' для линейки 18.x LTS начиная с 18.12.0. Другие кодовые имена LTS-релизов см. в архиве журнала изменений Node.js

{
  name: 'node',
  lts: 'Hydrogen',
  sourceUrl: 'https://nodejs.org/download/release/v18.12.0/node-v18.12.0.tar.gz',
  headersUrl: 'https://nodejs.org/download/release/v18.12.0/node-v18.12.0-headers.tar.gz',
  libUrl: 'https://nodejs.org/download/release/v18.12.0/win-x64/node.lib'
} copy

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

process.report

• <Object>

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

process.report.compact

• <boolean>

Записывать отчёты в компактном формате — однострочном JSON, который проще обрабатывать системами обработки логов, чем многострочный формат по умолчанию, предназначенный для чтения человеком.

import { report } from 'node:process';

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

const { report } = require('node:process');

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

process.report.directory

• <string>

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

import { report } from 'node:process';

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

const { report } = require('node:process');

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

process.report.filename

• <string>

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

Если для process.report.filename установлено значение 'stdout' или 'stderr', отчёт записывается в stdout или stderr процесса соответственно.

import { report } from 'node:process';

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

const { report } = require('node:process');

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

process.report.getReport([err])

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

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

import { report } from 'node:process';
import util from 'node:util';

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

// Similar to process.report.writeReport()
import fs from 'node:fs';
fs.writeFileSync('my-report.log', util.inspect(data), 'utf8');

const { report } = require('node:process');
const util = require('node:util');

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

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

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

process.report.reportOnFatalError

• <boolean>

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

import { report } from 'node:process';

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

const { report } = require('node:process');

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

process.report.reportOnSignal

• <boolean>

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

import { report } from 'node:process';

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

const { report } = require('node:process');

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

process.report.reportOnUncaughtException

• <boolean>

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

import { report } from 'node:process';

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

const { report } = require('node:process');

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

process.report.signal

• <string>

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

import { report } from 'node:process';

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

const { report } = require('node:process');

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

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

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

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

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

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

Если для filename установлено значение 'stdout' или 'stderr', отчёт записывается в stdout или stderr процесса соответственно.

import { report } from 'node:process';

report.writeReport();

const { report } = require('node:process');

report.writeReport();

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

process.resourceUsage()

• Возвращает: <Object> использование ресурсов текущим процессом. Все эти значения получены из вызова uv_getrusage, который возвращает структуру uv_rusage_t.
  • userCPUTime <integer> соответствует ru_utime, вычисленному в микросекундах. Это то же значение, что и process.cpuUsage().user.
  • systemCPUTime <integer> соответствует ru_stime, вычисленному в микросекундах. Это то же значение, что и process.cpuUsage().system.
  • maxRSS <integer> соответствует ru_maxrss — максимальному размеру резидентной части памяти (resident set size), использованному в килобайтах.
  • sharedMemorySize <integer> соответствует ru_ixrss, но не поддерживается ни на одной платформе.
  • unsharedDataSize <integer> соответствует ru_idrss, но не поддерживается ни на одной платформе.
  • unsharedStackSize <integer> соответствует ru_isrss, но не поддерживается ни на одной платформе.
  • minorPageFault <integer> соответствует ru_minflt — количеству незначительных ошибок страниц (minor page faults) для процесса; подробнее см. эту статью.
  • majorPageFault <integer> соответствует ru_majflt — количеству существенных ошибок страниц (major page faults) для процесса; подробнее см. эту статью. Это поле не поддерживается в Windows.
  • swappedOut <integer> соответствует ru_nswap, но не поддерживается ни на одной платформе.
  • fsRead <integer> соответствует ru_inblock — количеству операций ввода, выполненных файловой системой.
  • fsWrite <integer> соответствует ru_oublock — количеству операций вывода, выполненных файловой системой.
  • ipcSent <integer> соответствует ru_msgsnd, но не поддерживается ни на одной платформе.
  • ipcReceived <integer> соответствует ru_msgrcv, но не поддерживается ни на одной платформе.
  • signalsCount <integer> соответствует ru_nsignals, но не поддерживается ни на одной платформе.
  • voluntaryContextSwitches <integer> соответствует ru_nvcsw — количеству переключений контекста ЦП, произошедших из-за того, что процесс добровольно уступил процессор до завершения своего кванта времени (обычно в ожидании доступности ресурса). Это поле не поддерживается в Windows.
  • involuntaryContextSwitches <integer> соответствует ru_nivcsw — количеству переключений контекста ЦП, произошедших из-за того, что процесс с более высоким приоритетом стал готовым к выполнению, либо из-за превышения текущим процессом своего кванта времени. Это поле не поддерживается в Windows.

import { resourceUsage } from 'node:process';

console.log(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
  }
*/

const { resourceUsage } = require('node:process');

console.log(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 <Object>
• sendHandle <net.Server> | <net.Socket>
• options <Object> используется для параметризации отправки определённых типов дескрипторов (handles). options поддерживает следующие свойства:
  • keepOpen <boolean> Значение, которое можно использовать при передаче экземпляров net.Socket. Если true, сокет остаётся открытым в процессе-отправителе. По умолчанию: false.
• callback <Function>
• Возвращает: <boolean>

Если Node.js запущен с каналом IPC, метод process.send() можно использовать для отправки сообщений родительскому процессу. Сообщения будут приниматься как событие 'message' на объекте родителя ChildProcess.

Если Node.js был запущен без канала IPC, значение process.send будет undefined.

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

process.setegid(id)

• id <string> | <number> Имя или идентификатор группы

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

import process from 'node:process';

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

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

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

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

process.seteuid(id)

• id <string> | <number> Имя или идентификатор пользователя

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

import process from 'node:process';

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

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

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

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

process.setgid(id)

• id <string> | <number> Имя или идентификатор группы

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

import process from 'node:process';

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

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

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

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

process.setgroups(groups)

• groups <integer[]>

Метод process.setgroups() устанавливает идентификаторы дополнительных групп для процесса Node.js. Это привилегированная операция, требующая наличия у процесса Node.js прав root или привилегии CAP_SETGID.

Массив groups может содержать числовые идентификаторы групп, имена групп или и то, и другое.

import process from 'node:process';

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

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

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

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

process.setuid(id)

• id <integer> | <string>

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

import process from 'node:process';

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

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

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

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

process.setSourceMapsEnabled(val)

• val <boolean>

Эта функция включает или отключает поддержку Source Map v3 для трассировок стека.

Она предоставляет те же возможности, что и запуск процесса Node.js с параметрами командной строки --enable-source-maps.

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

process.setUncaughtExceptionCaptureCallback(fn)

• fn <Function> | <null>

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

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

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

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

process.sourceMapsEnabled

• <boolean>

Свойство process.sourceMapsEnabled возвращает значение, указывающее, включена ли поддержка Source Map v3 для трассировок стека.

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 до версии v0.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:

import { stdin, stdout } from 'node:process';

stdin.pipe(stdout);

const { stdin, stdout } = require('node:process');

stdin.pipe(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 copy

Дополнительную информацию см. в документации по 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' } copy

process.title

• <string>

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

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

Присвоение значения process.title может не отобразиться точно в диспетчерах процессов, таких как «Мониторинг системы» в macOS или «Диспетчер служб» в Windows.

process.traceDeprecation

• <boolean>

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

process.umask()

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

process.umask(mask)

• mask <string> | <integer>

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

import { umask } from 'node:process';

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

const { umask } = require('node:process');

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

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

process.uptime()

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

Метод process.uptime() возвращает время работы текущего процесса Node.js в секундах.

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

process.version

• <string>

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

import { version } from 'node:process';

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

const { version } = require('node:process');

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

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

process.versions

• <Object>

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

import { versions } from 'node:process';

console.log(versions);

const { versions } = require('node:process');

console.log(versions);

Сгенерирует объект, аналогичный следующему:

{ node: '23.0.0',
  acorn: '8.11.3',
  ada: '2.7.8',
  ares: '1.28.1',
  base64: '0.5.2',
  brotli: '1.1.0',
  cjs_module_lexer: '1.2.2',
  cldr: '45.0',
  icu: '75.1',
  llhttp: '9.2.1',
  modules: '127',
  napi: '9',
  nghttp2: '1.61.0',
  nghttp3: '0.7.0',
  ngtcp2: '1.3.0',
  openssl: '3.0.13+quic',
  simdjson: '3.8.0',
  simdutf: '5.2.4',
  tz: '2024a',
  undici: '6.13.0',
  unicode: '15.1',
  uv: '1.48.0',
  uvwasi: '0.0.20',
  v8: '12.4.254.14-node.11',
  zlib: '1.3.0.1-motley-7d77fb7' } copy

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

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

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