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

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

Событие: 'beforeExit'

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

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

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

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

MJS модули

import process from '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

CJS модули

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

Событие: 'exit'

• code <целое число>

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

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

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

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

MJS модули

import process from 'process';

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

CJS модули

const process = require('process');

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

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

MJS модули

import process from 'process';

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

CJS модули

const process = require('process');

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

Событие: 'message'

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

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

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

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

Событие: 'multipleResolves'

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

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

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

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

MJS модули

import process from '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

CJS модули

const process = require('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> Обработанный позже promise.

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

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

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

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

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

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

MJS модули

import process from 'process';

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

CJS модули

const process = require('process');

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

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

Событие: 'uncaughtException'

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

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

MJS модули

import process from 'process';

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

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

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

CJS модули

const process = require('process');

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

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

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

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

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

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

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

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

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

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

Событие: 'uncaughtExceptionMonitor'

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

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

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

MJS модули

import process from 'process';

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

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

CJS модули

const process = require('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' полезно для обнаружения и отслеживания отклоненных промисов, чьи отклонения ещё не обработаны.

MJS модули

import process from '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()`

CJS модули

const process = require('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'.

MJS модули

import process from '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

CJS модули

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

Событие: 'warning'

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

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

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

MJS модули

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

CJS модули

const process = require('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.

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

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

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

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

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

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

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

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

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

Событие: 'worker'

• worker <Worker> Созданная нить <Worker>.

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

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

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

Имена предупреждений Node.js

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

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

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

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

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

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

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

MJS модули

import process from '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);

CJS модули

const process = require('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). Для него можно установить обработчик, однако Node.js будет безусловно завершен Windows примерно через 10 секунд. На платформах, отличных от Windows, поведение SIGHUP по умолчанию — завершить Node.js, но после установки обработчика его поведение по умолчанию будет удалено.
• 'SIGTERM' не поддерживается в Windows, на него можно установить обработчик.
• 'SIGINT' из терминала поддерживается на всех платформах и обычно генерируется нажатием Ctrl+C (хотя это может быть настраиваемо). Он не генерируется, когда включён режим сырого режима терминала и используется Ctrl+C.
• 'SIGBREAK' доставляется в Windows при нажатии Ctrl+Break. На платформах, отличных от Windows, на него можно установить обработчик, но нет способа его отправить или сгенерировать.
• 'SIGWINCH' доставляется при изменении размера консоли. В Windows это произойдёт только при записи в консоль, когда курсор перемещается или используется читаемый tty в сыром режиме.
• 'SIGKILL' не может иметь установленный обработчик, он безусловно завершит Node.js на всех платформах.
• 'SIGSTOP' не может иметь установленный обработчик.
• 'SIGBUS', 'SIGFPE', 'SIGSEGV' и 'SIGILL', если они не генерируются искусственно с помощью kill(2), по своей природе оставляют процесс в состоянии, при котором вызов JS-обработчиков небезопасен. Это может привести к тому, что процесс перестанет отвечать.
• 0 можно отправить, чтобы проверить существование процесса. Если процесс существует, это не повлияет на него, но если процесса нет, будет выброшено исключение.

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

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

process.abort()

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

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

process.allowedNodeEnvironmentFlags

• <Set>

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

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

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

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

Модули MJS

import { allowedNodeEnvironmentFlags } from 'process';

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

Модули CJS

const { allowedNodeEnvironmentFlags } = require('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

• <строка>

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

Модули MJS

import { arch } from 'process';

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

Модули CJS

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

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

process.argv

• <массив строк>

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

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

Модули MJS

import { argv } from 'process';

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

Модули CJS

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

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

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

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

Даст следующий вывод:

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

process.argv0

• <строка>

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

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

process.channel

• <объект>

Если процесс 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 <строка>

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

Модули MJS

import { chdir, cwd } from 'process';

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

Модули CJS

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

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

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

process.config

• <Объект>

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

Пример возможного результата:

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

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

Изменение свойства process.config или любого вложенного свойства объекта process.config устарело. Свойство process.config будет сделано неизменяемым в будущей версии.

process.connected

• <булево>

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

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

process.cpuUsage([previousValue])

• previousValue <Объект> Предыдущее значение возвращаемое вызовом process.cpuUsage()
• Возвращает: <Объект>
  • user <целое>
  • system <целое>

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

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

Модули MJS

import { cpuUsage } from '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 }

Модули CJS

const { cpuUsage } = require('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()

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

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

Модули MJS

import { cwd } from 'process';

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

Модули CJS

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

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

process.debugPort

• <число>

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

Модули MJS

import process from 'process';

process.debugPort = 5858;

Модули CJS

const process = require('process');

process.debugPort = 5858;

process.disconnect()

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

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

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

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

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

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

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

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

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

Модули MJS

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

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

Модули CJS

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

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

process.emitWarning(warning[, options])

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

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

Модули MJS

import { emitWarning } from '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

Модули CJS

const { emitWarning } = require('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'.

Модули MJS

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

Модули CJS

const process = require('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 передаётся как объект, аргумент options игнорируется.

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

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

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

MJS модули

import { emitWarning } from 'process';

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

CJS модули

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

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

MJS модули

import { emitWarning } from 'process';

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

CJS модули

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

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

MJS модули

import { emitWarning } from 'process';

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

CJS модули

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

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

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

MJS модули

import process from 'process';

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

CJS модули

const process = require('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 будут проигнорированы):

MJS модули

import { emitWarning } from '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!

CJS модули

const { emitWarning } = require('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() за простой логической переменной, как показано в примере ниже:

MJS модули

import { emitWarning } from 'process';

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

CJS модули

const { emitWarning } = require('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

• <Объект>

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

Пример такого объекта выглядит так:

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

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

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

В то время как следующее сработает:

MJS модули

import { env } from 'process';

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

CJS модули

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

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

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

MJS модули

import { env } from 'process';

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

CJS модули

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

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

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

MJS модули

import { env } from 'process';

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

CJS модули

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

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

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

MJS модули

import { env } from 'process';

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

CJS модули

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

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

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

process.execArgv

• <массив строк>

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

$ node --harmony script.js --version

Результат process.execArgv:

['--harmony']

И process.argv:

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

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

process.execPath

• <строка>

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

'/usr/local/bin/node'

process.exit([code])

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

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

Для завершения с кодом «ошибка»:

Модули MJS

import { exit } from 'process';

exit(1);

Модули CJS

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

exit(1);

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

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

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

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

Модули MJS

import { exit } from 'process';

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

Модули CJS

const { exit } = require('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 и позволить процессу завершиться естественным путём, избегая планирования дополнительной работы для цикла событий:

Модули MJS

import process from 'process';

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

Модули CJS

const process = require('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

• <целое>

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

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

process.getegid()

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

Модули MJS

import process from 'process';

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

Модули CJS

const process = require('process');

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

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

process.geteuid()

• Возвращает: <Объект>

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

Модули MJS

import process from 'process';

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

Модули CJS

const process = require('process');

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

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

process.getgid()

• Возвращает: <Объект>

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

Модули MJS

import process from 'process';

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

Модули CJS

const process = require('process');

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

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

process.getgroups()

• Возвращает: <массив целых>

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

Модули MJS

import process from 'process';

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

Модули CJS

const process = require('process');

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

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

process.getuid()

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

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

Модули MJS

import process from 'process';

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

Модули CJS

const process = require('process');

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

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

process.hasUncaughtExceptionCaptureCallback()

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

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

process.hrtime([time])

• time <массив целых> Результат предыдущего вызова process.hrtime()
• Возвращает: <массив целых>

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

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

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

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

Модули MJS

import { hrtime } from '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);

Модули CJS

const { hrtime } = require('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.

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

Модули MJS

import { hrtime } from 'process';

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

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

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

Модули CJS

const { hrtime } = require('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.

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

Модули MJS

import { getgroups, initgroups, setgid } from '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 ]

Модули CJS

const { getgroups, initgroups, setgid } = require('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. Отправленный сигнал может выполнить действие, отличное от завершения целевого процесса.

Модули MJS

import process, { kill } from 'process';

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

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

kill(process.pid, 'SIGHUP');

Модули CJS

const process = require('process');

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

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

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

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

process.mainModule

• <Объект>

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

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

process.memoryUsage()

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

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

Модули MJS

import { memoryUsage } from 'process';

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

Модули CJS

const { memoryUsage } = require('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, включая все Node.js Buffer. Эта величина также входит в значение external. При использовании Node.js как встроенной библиотеки это значение может быть 0, поскольку выделения памяти для ArrayBuffer могут не отслеживаться в этом случае.

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

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

process.memoryUsage.rss()

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

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

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

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

Модули MJS

import { memoryUsage } from 'process';

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

Модули CJS

const { rss } = require('process');

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

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

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

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

Модули MJS

import { nextTick } from 'process';

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

Модули CJS

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

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

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

Модули MJS

import { nextTick } from 'process';

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

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

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

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

Модули CJS

const { nextTick } = require('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);
}

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

const maybeTrue = Math.random() > 0.5;

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

bar();

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

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

Модули MJS

import { nextTick } from 'process';

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

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

Модули CJS

const { nextTick } = require('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 каждый раз, когда очередь "next tick" обрабатывается, очередь микрозадач обрабатывается сразу после этого.

Модули MJS

import { nextTick } from 'process';

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

Модули CJS

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

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

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

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

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

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

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

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

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

process.noDeprecation

• <логический>

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

process.pid

• <целое число>

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

Модули MJS

import { pid } from 'process';

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

Модули CJS

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

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

process.platform

• <строка>

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

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

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

Модули MJS

import { platform } from 'process';

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

Модули CJS

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

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

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

process.ppid

• <целое число>

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

Модули MJS

import { ppid } from 'process';

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

Модули CJS

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

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

process.release

• <Объект>

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

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

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

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

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

process.report

• <Объект>

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

process.report.compact

• <булево>

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

Модули MJS

import { report } from 'process';

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

Модули CJS

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

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

process.report.directory

• <строка>

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

Модули MJS

import { report } from 'process';

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

Модули CJS

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

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

process.report.filename

• <строка>

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

Модули MJS

import { report } from 'process';

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

Модули CJS

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

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

process.report.getReport([err])

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

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

Модули MJS

import { report } from 'process';

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

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

Модули CJS

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

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

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

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

process.report.reportOnFatalError

• <булево>

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

Модули MJS

import { report } from 'process';

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

Модули CJS

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

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

process.report.reportOnSignal

• <булево>

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

Модули MJS

import { report } from 'process';

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

Модули CJS

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

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

process.report.reportOnUncaughtException

• <булево>

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

Модули MJS

import { report } from 'process';

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

Модули CJS

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

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

process.report.signal

• <строка>

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

Модули MJS

import { report } from 'process';

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

Модули CJS

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

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

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

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

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

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

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

Модули MJS

import { report } from 'process';

report.writeReport();

Модули CJS

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

report.writeReport();

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

process.resourceUsage()

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

Модули MJS

import { resourceUsage } from '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
  }
*/

Модули CJS

const { resourceUsage } = require('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 <Объект>
• sendHandle <net.Сервер> | <net.Сокет>
• options <Объект> используется для параметризации отправки определённых типов дескрипторов. options поддерживает следующие свойства:
  • keepOpen <логическое значение> Значение, которое может быть использовано при передаче экземпляров net.Socket. Если true, сокет будет оставаться открытым в процессе отправки. По умолчанию: false.
• callback <Функция>
• Возвращает: <логическое значение>

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

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

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

process.setegid(id)

• id <строка> | <число> Имя или ID группы

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

Модули MJS

import process from '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.log(`Failed to set gid: ${err}`);
  }
}

Модули CJS

const process = require('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.log(`Failed to set gid: ${err}`);
  }
}

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

process.seteuid(id)

• id <строка> | <число> Имя или ID пользователя

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

Модули MJS

import process from '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.log(`Failed to set uid: ${err}`);
  }
}

Модули CJS

const process = require('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.log(`Failed to set uid: ${err}`);
  }
}

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

process.setgid(id)

• id <строка> | <число> Имя или ID группы

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

Модули MJS

import process from '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.log(`Failed to set gid: ${err}`);
  }
}

Модули CJS

const process = require('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.log(`Failed to set gid: ${err}`);
  }
}

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

process.setgroups(groups)

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

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

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

Модули MJS

import process from 'process';

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

Модули CJS

const process = require('process');

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

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

process.setuid(id)

• id <целое> | <строка>

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

Модули MJS

import process from '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.log(`Failed to set uid: ${err}`);
  }
}

Модули CJS

const process = require('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.log(`Failed to set uid: ${err}`);
  }
}

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

process.setSourceMapsEnabled(val)

• val <булево>

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

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

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

process.setUncaughtExceptionCaptureCallback(fn)

• fn <Функция> | <null>

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

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

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

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

process.stderr

• <Поток>

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

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

process.stderr.fd

• <число>

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

process.stdin

• <Поток>

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

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

Как поток типа «Duplex», process.stdin также может использоваться в «старом» режиме, совместимом со скриптами, написанными для Node.js до версии v0.10. Дополнительная информация приведена в Совместимость потоков.

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

process.stdin.fd

• <число>

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

process.stdout

• <Поток>

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

Например, чтобы скопировать process.stdin в process.stdout:

Модули MJS

import { stdin, stdout } from 'process';

stdin.pipe(stdout);

Модули CJS

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

stdin.pipe(stdout);

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

process.stdout.fd

• <число>

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

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

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

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

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

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

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

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

Например:

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

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

process.throwDeprecation

• <булево>

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

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

process.title

• <строка>

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

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

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

process.traceDeprecation

• <логическое>

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

process.umask()

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

process.umask(mask)

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

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

Модули MJS

import { umask } from 'process';

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

Модули CJS

const { umask } = require('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()

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

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

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

process.version

• <строка>

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

Модули MJS

import { version } from 'process';

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

Модули CJS

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

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

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

process.versions

• <Объект>

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

Модули MJS

import { versions } from 'process';

console.log(versions);

Модули CJS

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

console.log(versions);

Сгенерирует объект, похожий на:

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

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

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

• 1 Необработанное критическое исключение: произошла необработанная ошибка, и она не обрабатывалась областью или обработчиком события 'uncaughtException'.
• 2: Не используется (зарезервировано Bash для некорректного использования встроенных функций)
• 3 Внутренняя ошибка синтаксического анализа JavaScript: Внутренний код 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 Незавершенный верхнеуровневый ожидания: await был использован вне функции в коде верхнего уровня, но переданный Promise никогда не завершался.
• >128 Завершения сигналов: Если Node.js получает фатальный сигнал, такой как SIGKILL или SIGHUP, то его код завершения будет 128 плюс значение кода сигнала. Это стандартная практика POSIX, так как коды завершения определены как 7-битные целые числа, а завершения сигналов устанавливают старший бит, а затем содержат значение кода сигнала. Например, сигнал SIGABRT имеет значение 6, поэтому ожидаемый код завершения будет 128 + 6, или 134.