Processo

O objeto process fornece informações e controle sobre o processo Node.js atual.

ESMCJS

import process from 'node:process';

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

Eventos do Processo

O objeto process é uma instância de EventEmitter.

Evento: `'beforeExit'`

Adicionado em: v0.11.12

O evento 'beforeExit' é emitido quando o Node.js esvazia seu loop de eventos e não tem trabalho adicional para agendar. Normalmente, o processo Node.js será encerrado quando não houver trabalho agendado, mas um listener registrado no evento 'beforeExit' pode fazer chamadas assíncronas e, assim, fazer com que o processo Node.js continue.

A função de callback do listener é invocada com o valor de process.exitCode passado como o único argumento.

O evento 'beforeExit' não é emitido para condições que causam terminação explícita, como chamar process.exit() ou exceções não capturadas.

O 'beforeExit' não deve ser usado como uma alternativa ao evento 'exit' a menos que a intenção seja agendar trabalho adicional.

ESMCJS

import process from 'node:process';

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

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

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

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

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

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

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

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

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

Evento: `'disconnect'`

Adicionado em: v0.7.7

Se o processo Node.js for gerado com um canal IPC (veja a documentação de Processo Filho e Cluster), o evento 'disconnect' será emitido quando o canal IPC for fechado.

Evento: `'exit'`

Adicionado em: v0.1.7

code <integer>

O evento 'exit' é emitido quando o processo Node.js está prestes a ser encerrado como resultado de:

O método process.exit() sendo chamado explicitamente;
O loop de eventos do Node.js não ter mais nenhum trabalho adicional a ser realizado.

Não há como impedir a saída do loop de eventos neste ponto e, uma vez que todos os listeners de 'exit' terminarem de ser executados, o processo Node.js será encerrado.

A função de callback do listener é invocada com o código de saída especificado pela propriedade process.exitCode ou pelo argumento exitCode passado para o método process.exit().

ESMCJS

import process from 'node:process';

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

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

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

As funções de listener devem apenas realizar operações síncronas. O processo Node.js será encerrado imediatamente após chamar os listeners de evento 'exit', fazendo com que qualquer trabalho adicional ainda enfileirado no loop de eventos seja abandonado. No exemplo a seguir, por exemplo, o timeout nunca ocorrerá:

ESMCJS

import process from 'node:process';

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

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

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

Evento: `'message'`

Adicionado em: v0.5.10

message <Objeto> | <booleano> | <número> | <string> | <nulo> um objeto JSON analisado ou um valor primitivo serializável.
sendHandle <net.Server> | <net.Socket> um objeto net.Server ou net.Socket, ou indefinido.

Se o processo Node.js for gerado com um canal IPC (consulte a documentação de Processo Filho e Cluster), o evento 'message' é emitido sempre que uma mensagem enviada por um processo pai usando childprocess.send() é recebida pelo processo filho.

A mensagem passa por serialização e análise. A mensagem resultante pode não ser a mesma que foi enviada originalmente.

Se a opção serialization foi definida como advanced ao gerar o processo, o argumento message pode conter dados que o JSON não consegue representar. Consulte Serialização avançada para child_process para obter mais detalhes.

Evento: `'multipleResolves'`

Adicionado em: v10.12.0

Obsoleto desde: v17.6.0, v16.15.0

[Estável: 0 - Obsoleto]

Estável: 0 Estabilidade: 0 - Obsoleto

type <string> O tipo de resolução. Um de 'resolve' ou 'reject'.
promise <Promise> A promise que resolveu ou rejeitou mais de uma vez.
value <any> O valor com o qual a promise foi resolvida ou rejeitada após a resolução original.

O evento 'multipleResolves' é emitido sempre que uma Promise foi:

Resolvida mais de uma vez.
Rejeitada mais de uma vez.
Rejeitada após a resolução.
Resolvida após a rejeição.

Isso é útil para rastrear possíveis erros em um aplicativo ao usar o construtor Promise, pois várias resoluções são ignoradas silenciosamente. No entanto, a ocorrência desse evento não indica necessariamente um erro. Por exemplo, Promise.race() pode acionar um evento 'multipleResolves'.

Devido à falta de confiabilidade do evento em casos como o exemplo Promise.race() acima, ele foi descontinuado.

ESMCJS

import process from 'node:process';

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

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

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

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

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

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

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

Evento: `'rejectionHandled'`

Adicionado em: v1.4.1

promise <Promise> A promessa tratada tardiamente.

O evento 'rejectionHandled' é emitido sempre que uma Promise foi rejeitada e um manipulador de erros foi anexado a ela (usando promise.catch(), por exemplo) posteriormente a uma volta do loop de eventos do Node.js.

O objeto Promise teria sido previamente emitido em um evento 'unhandledRejection', mas durante o curso do processamento ganhou um manipulador de rejeição.

Não há noção de um nível superior para uma cadeia Promise no qual as rejeições sempre podem ser tratadas. Sendo inerentemente assíncrona em sua natureza, uma rejeição de Promise pode ser tratada em um ponto futuro no tempo, possivelmente muito mais tarde do que a volta do loop de eventos que leva para o evento 'unhandledRejection' ser emitido.

Outra maneira de dizer isso é que, ao contrário do código síncrono, onde há uma lista cada vez maior de exceções não tratadas, com Promises pode haver uma lista crescente e decrescente de rejeições não tratadas.

No código síncrono, o evento 'uncaughtException' é emitido quando a lista de exceções não tratadas cresce.

No código assíncrono, o evento 'unhandledRejection' é emitido quando a lista de rejeições não tratadas cresce e o evento 'rejectionHandled' é emitido quando a lista de rejeições não tratadas diminui.

ESMCJS

import process from 'node:process';

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

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

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

Neste exemplo, o Map unhandledRejections crescerá e diminuirá com o tempo, refletindo as rejeições que começam não tratadas e depois se tornam tratadas. É possível registrar tais erros em um log de erros, seja periodicamente (o que provavelmente é melhor para aplicações de longa duração) ou ao sair do processo (o que provavelmente é mais conveniente para scripts).

Evento: `'workerMessage'`

Adicionado em: v22.5.0

value <any> Um valor transmitido usando postMessageToThread().
source <number> O ID da thread de worker de transmissão ou 0 para a thread principal.

O evento 'workerMessage' é emitido para qualquer mensagem de entrada enviada pela outra parte usando postMessageToThread().

Evento: `'uncaughtException'`

[Histórico]

Versão	Mudanças
v12.0.0, v10.17.0	Adicionado o argumento `origin`.
v0.1.18	Adicionado em: v0.1.18

err <Error> A exceção não capturada.
origin <string> Indica se a exceção se origina de uma rejeição não tratada ou de um erro síncrono. Pode ser 'uncaughtException' ou 'unhandledRejection'. O último é usado quando uma exceção acontece em um contexto assíncrono baseado em Promise (ou se uma Promise é rejeitada) e a flag --unhandled-rejections está definida como strict ou throw (que é o padrão) e a rejeição não é tratada, ou quando uma rejeição acontece durante a fase de carregamento estático do módulo ES do ponto de entrada da linha de comando.

O evento 'uncaughtException' é emitido quando uma exceção JavaScript não capturada borbulha de volta ao loop de eventos. Por padrão, o Node.js lida com tais exceções imprimindo o stack trace para stderr e saindo com o código 1, substituindo qualquer process.exitCode definido anteriormente. Adicionar um manipulador para o evento 'uncaughtException' substitui este comportamento padrão. Alternativamente, altere o process.exitCode no manipulador 'uncaughtException' que resultará na saída do processo com o código de saída fornecido. Caso contrário, na presença de tal manipulador, o processo sairá com 0.

ESMCJS

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

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

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

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

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

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

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

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

É possível monitorar eventos 'uncaughtException' sem substituir o comportamento padrão de sair do processo, instalando um listener 'uncaughtExceptionMonitor'.

Aviso: Usando `'uncaughtException'` corretamente

'uncaughtException' é um mecanismo bruto para tratamento de exceções destinado a ser usado apenas como último recurso. O evento não deve ser usado como equivalente a On Error Resume Next. Exceções não tratadas inerentemente significam que um aplicativo está em um estado indefinido. Tentar retomar o código do aplicativo sem se recuperar adequadamente da exceção pode causar problemas adicionais imprevistos e imprevisíveis.

Exceções lançadas de dentro do manipulador de eventos não serão capturadas. Em vez disso, o processo será encerrado com um código de saída diferente de zero e o rastreamento de pilha será impresso. Isso é para evitar recursão infinita.

Tentar retomar normalmente após uma exceção não capturada pode ser semelhante a puxar o cabo de alimentação ao atualizar um computador. Nove em cada dez vezes, nada acontece. Mas na décima vez, o sistema é corrompido.

O uso correto de 'uncaughtException' é realizar a limpeza síncrona de recursos alocados (por exemplo, descritores de arquivo, handles, etc.) antes de desligar o processo. Não é seguro retomar a operação normal após 'uncaughtException'.

Para reiniciar um aplicativo travado de uma forma mais confiável, seja 'uncaughtException' emitido ou não, um monitor externo deve ser empregado em um processo separado para detectar falhas de aplicativos e recuperar ou reiniciar conforme necessário.

Evento: `'uncaughtExceptionMonitor'`

Adicionado em: v13.7.0, v12.17.0

err <Error> A exceção não capturada.
origin <string> Indica se a exceção se origina de uma rejeição não tratada ou de erros síncronos. Pode ser 'uncaughtException' ou 'unhandledRejection'. O último é usado quando uma exceção acontece em um contexto assíncrono baseado em Promise (ou se uma Promise é rejeitada) e o sinalizador --unhandled-rejections está definido como strict ou throw (que é o padrão) e a rejeição não é tratada, ou quando uma rejeição acontece durante a fase de carregamento estático do módulo ES do ponto de entrada da linha de comando.

O evento 'uncaughtExceptionMonitor' é emitido antes que um evento 'uncaughtException' seja emitido ou um hook instalado via process.setUncaughtExceptionCaptureCallback() seja chamado.

Instalar um listener 'uncaughtExceptionMonitor' não altera o comportamento uma vez que um evento 'uncaughtException' é emitido. O processo ainda travará se nenhum listener 'uncaughtException' estiver instalado.

ESMCJS

import process from 'node:process';

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

// Intencionalmente cause uma exceção, mas não a capture.
nonexistentFunc();
// Ainda trava o Node.js

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

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

// Intencionalmente cause uma exceção, mas não a capture.
nonexistentFunc();
// Ainda trava o Node.js

Evento: `'unhandledRejection'`

[Histórico]

Versão	Mudanças
v7.0.0	Não tratar rejeições de `Promise` está obsoleto.
v6.6.0	Rejeições de `Promise` não tratadas agora emitirão um aviso do processo.
v1.4.1	Adicionado em: v1.4.1

reason <Error> | <any> O objeto com o qual a promise foi rejeitada (tipicamente um objeto Error).
promise <Promise> A promise rejeitada.

O evento 'unhandledRejection' é emitido sempre que uma Promise é rejeitada e nenhum manipulador de erros é anexado à promise dentro de um ciclo do event loop. Ao programar com Promises, exceções são encapsuladas como "promises rejeitadas". Rejeições podem ser capturadas e tratadas usando promise.catch() e são propagadas através de uma cadeia de Promise. O evento 'unhandledRejection' é útil para detectar e acompanhar promises que foram rejeitadas e cujas rejeições ainda não foram tratadas.

ESMCJS

import process from 'node:process';

process.on('unhandledRejection', (reason, promise) => {
  console.log('Rejeição Não Tratada em:', promise, 'razão:', reason);
  // Registro específico da aplicação, lançando um erro ou outra lógica aqui
});

somePromise.then((res) => {
  return reportToUser(JSON.pasre(res)); // Observe o erro de digitação (`pasre`)
}); // Sem `.catch()` ou `.then()`

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

process.on('unhandledRejection', (reason, promise) => {
  console.log('Rejeição Não Tratada em:', promise, 'razão:', reason);
  // Registro específico da aplicação, lançando um erro ou outra lógica aqui
});

somePromise.then((res) => {
  return reportToUser(JSON.pasre(res)); // Observe o erro de digitação (`pasre`)
}); // Sem `.catch()` ou `.then()`

O seguinte também irá disparar a emissão do evento 'unhandledRejection':

ESMCJS

import process from 'node:process';

function SomeResource() {
  // Inicialmente define o status carregado para uma promise rejeitada
  this.loaded = Promise.reject(new Error('Recurso ainda não carregado!'));
}

const resource = new SomeResource();
// sem .catch ou .then em resource.loaded por pelo menos um ciclo

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

function SomeResource() {
  // Inicialmente define o status carregado para uma promise rejeitada
  this.loaded = Promise.reject(new Error('Recurso ainda não carregado!'));
}

const resource = new SomeResource();
// sem .catch ou .then em resource.loaded por pelo menos um ciclo

Neste caso de exemplo, é possível rastrear a rejeição como um erro de desenvolvedor, como normalmente seria o caso para outros eventos 'unhandledRejection'. Para resolver tais falhas, um manipulador .catch(() =\> { }) não operacional pode ser anexado a resource.loaded, o que impediria que o evento 'unhandledRejection' fosse emitido.

Evento: `'warning'`

Adicionado em: v6.0.0

warning <Error> As propriedades principais do aviso são:
- name <string> O nome do aviso. Padrão: 'Warning'.
- message <string> Uma descrição do aviso fornecida pelo sistema.
- stack <string> Um rastreamento de pilha para o local no código onde o aviso foi emitido.

O evento 'warning' é emitido sempre que o Node.js emite um aviso de processo.

Um aviso de processo é semelhante a um erro, pois descreve condições excepcionais que estão sendo trazidas à atenção do usuário. No entanto, os avisos não fazem parte do fluxo normal de tratamento de erros do Node.js e do JavaScript. O Node.js pode emitir avisos sempre que detectar práticas de codificação ruins que podem levar a um desempenho subótimo do aplicativo, bugs ou vulnerabilidades de segurança.

ESMCJS

import process from 'node:process';

process.on('warning', (warning) => {
  console.warn(warning.name);    // Imprime o nome do aviso
  console.warn(warning.message); // Imprime a mensagem do aviso
  console.warn(warning.stack);   // Imprime o rastreamento de pilha
});

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

process.on('warning', (warning) => {
  console.warn(warning.name);    // Imprime o nome do aviso
  console.warn(warning.message); // Imprime a mensagem do aviso
  console.warn(warning.stack);   // Imprime o rastreamento de pilha
});

Por padrão, o Node.js imprimirá avisos de processo para stderr. A opção de linha de comando --no-warnings pode ser usada para suprimir a saída padrão do console, mas o evento 'warning' ainda será emitido pelo objeto process. Atualmente, não é possível suprimir tipos de aviso específicos além dos avisos de depreciação. Para suprimir avisos de depreciação, consulte o sinalizador --no-deprecation.

O exemplo a seguir ilustra o aviso que é impresso em stderr quando muitos listeners foram adicionados a um evento:

bash

$ 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

Em contraste, o exemplo a seguir desativa a saída de aviso padrão e adiciona um manipulador personalizado ao evento 'warning':

bash

$ 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!

A opção de linha de comando --trace-warnings pode ser usada para que a saída padrão do console para avisos inclua o rastreamento de pilha completo do aviso.

Iniciar o Node.js usando o sinalizador de linha de comando --throw-deprecation fará com que avisos de depreciação personalizados sejam lançados como exceções.

Usar o sinalizador de linha de comando --trace-deprecation fará com que a depreciação personalizada seja impressa em stderr junto com o rastreamento de pilha.

Usar o sinalizador de linha de comando --no-deprecation suprimirá todos os relatórios da depreciação personalizada.

Os sinalizadores de linha de comando *-deprecation afetam apenas os avisos que usam o nome 'DeprecationWarning'.

Emitindo avisos personalizados

Consulte o método process.emitWarning() para emitir avisos personalizados ou específicos da aplicação.

Nomes de avisos do Node.js

Não existem diretrizes rígidas para os tipos de aviso (conforme identificado pela propriedade name) emitidos pelo Node.js. Novos tipos de avisos podem ser adicionados a qualquer momento. Alguns dos tipos de avisos mais comuns incluem:

'DeprecationWarning' - Indica o uso de uma API ou funcionalidade obsoleta do Node.js. Tais avisos devem incluir uma propriedade 'code' identificando o código de depreciação.
'ExperimentalWarning' - Indica o uso de uma API ou funcionalidade experimental do Node.js. Tais funcionalidades devem ser usadas com cautela, pois podem mudar a qualquer momento e não estão sujeitas às mesmas políticas estritas de versionamento semântico e suporte de longo prazo que as funcionalidades suportadas.
'MaxListenersExceededWarning' - Indica que muitos listeners para um determinado evento foram registrados em um EventEmitter ou EventTarget. Isso geralmente é uma indicação de um vazamento de memória.
'TimeoutOverflowWarning' - Indica que um valor numérico que não cabe em um inteiro de 32 bits com sinal foi fornecido para as funções setTimeout() ou setInterval().
'TimeoutNegativeWarning' - Indica que um número negativo foi fornecido para as funções setTimeout() ou setInterval().
'TimeoutNaNWarning' - Indica que um valor que não é um número foi fornecido para as funções setTimeout() ou setInterval().
'UnsupportedWarning' - Indica o uso de uma opção ou funcionalidade não suportada que será ignorada em vez de tratada como um erro. Um exemplo é o uso da mensagem de status de resposta HTTP ao usar a API de compatibilidade HTTP/2.

Evento: `'worker'`

Adicionado em: v16.2.0, v14.18.0

worker <Worker> O <Worker> que foi criado.

O evento 'worker' é emitido após a criação de uma nova thread <Worker>.

Eventos de Sinal

Eventos de sinal serão emitidos quando o processo do Node.js receber um sinal. Consulte signal(7) para obter uma lista de nomes de sinais POSIX padrão, como 'SIGINT', 'SIGHUP', etc.

Sinais não estão disponíveis em threads Worker.

O manipulador de sinal receberá o nome do sinal ('SIGINT', 'SIGTERM', etc.) como o primeiro argumento.

O nome de cada evento será o nome comum em maiúsculas para o sinal (por exemplo, 'SIGINT' para sinais SIGINT).

ESMCJS

import process from 'node:process';

// Comece a ler do stdin para que o processo não seja encerrado.
process.stdin.resume();

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

// Usando uma única função para lidar com vários sinais
function handle(signal) {
  console.log(`Received ${signal}`);
}

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

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

// Comece a ler do stdin para que o processo não seja encerrado.
process.stdin.resume();

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

// Usando uma única função para lidar com vários sinais
function handle(signal) {
  console.log(`Received ${signal}`);
}

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

'SIGUSR1' é reservado pelo Node.js para iniciar o depurador. É possível instalar um listener, mas fazê-lo pode interferir no depurador.
'SIGTERM' e 'SIGINT' têm manipuladores padrão em plataformas não Windows que redefinem o modo de terminal antes de sair com o código 128 + número do sinal. Se um desses sinais tiver um listener instalado, seu comportamento padrão será removido (o Node.js não será mais encerrado).
'SIGPIPE' é ignorado por padrão. Ele pode ter um listener instalado.
'SIGHUP' é gerado no Windows quando a janela do console é fechada e, em outras plataformas, sob várias condições semelhantes. Consulte signal(7). Ele pode ter um listener instalado, no entanto, o Node.js será incondicionalmente terminado pelo Windows cerca de 10 segundos depois. Em plataformas não Windows, o comportamento padrão de SIGHUP é terminar o Node.js, mas uma vez que um listener tenha sido instalado, seu comportamento padrão será removido.
'SIGTERM' não é suportado no Windows, ele pode ser escutado.
'SIGINT' do terminal é suportado em todas as plataformas e geralmente pode ser gerado com + (embora isso possa ser configurável). Ele não é gerado quando o modo bruto do terminal está habilitado e + é usado.
'SIGBREAK' é entregue no Windows quando + é pressionado. Em plataformas não Windows, ele pode ser escutado, mas não há como enviá-lo ou gerá-lo.
'SIGWINCH' é entregue quando o console foi redimensionado. No Windows, isso só acontecerá na gravação no console quando o cursor estiver sendo movido ou quando um tty legível for usado no modo bruto.
'SIGKILL' não pode ter um listener instalado, ele terminará incondicionalmente o Node.js em todas as plataformas.
'SIGSTOP' não pode ter um listener instalado.
'SIGBUS', 'SIGFPE', 'SIGSEGV' e 'SIGILL', quando não levantados artificialmente usando kill(2), inerentemente deixam o processo em um estado do qual não é seguro chamar listeners JS. Fazer isso pode fazer com que o processo pare de responder.
0 pode ser enviado para testar a existência de um processo, não tem efeito se o processo existir, mas lançará um erro se o processo não existir.

O Windows não suporta sinais, portanto, não tem equivalente à terminação por sinal, mas o Node.js oferece alguma emulação com process.kill() e subprocess.kill():

O envio de SIGINT, SIGTERM e SIGKILL causará a terminação incondicional do processo de destino e, posteriormente, o subprocesso relatará que o processo foi terminado por sinal.
O envio do sinal 0 pode ser usado como uma forma independente de plataforma para testar a existência de um processo.

`process.abort()`

Adicionado em: v0.7.0

O método process.abort() faz com que o processo Node.js saia imediatamente e gere um arquivo core.

Este recurso não está disponível nas threads Worker.

`process.allowedNodeEnvironmentFlags`

Adicionado em: v10.10.0

<Set>

A propriedade process.allowedNodeEnvironmentFlags é um Set especial, somente leitura, de flags permitidas dentro da variável de ambiente NODE_OPTIONS.

process.allowedNodeEnvironmentFlags estende Set, mas substitui Set.prototype.has para reconhecer várias representações possíveis de flags. process.allowedNodeEnvironmentFlags.has() retornará true nos seguintes casos:

As flags podem omitir hífens únicos (-) ou duplos (--) iniciais; por exemplo, inspect-brk para --inspect-brk, ou r para -r.
As flags passadas para o V8 (conforme listado em --v8-options) podem substituir um ou mais hífens não iniciais por um sublinhado, ou vice-versa; por exemplo, --perf_basic_prof, --perf-basic-prof, --perf_basic-prof, etc.
As flags podem conter um ou mais caracteres de igual (=); todos os caracteres após e incluindo o primeiro sinal de igual serão ignorados; por exemplo, --stack-trace-limit=100.
As flags devem ser permitidas dentro de NODE_OPTIONS.

Ao iterar sobre process.allowedNodeEnvironmentFlags, as flags aparecerão apenas uma vez; cada uma começará com um ou mais hífens. As flags passadas para o V8 conterão sublinhados em vez de hífens não iniciais:

ESMCJS

import { allowedNodeEnvironmentFlags } from 'node:process';

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

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

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

Os métodos add(), clear() e delete() de process.allowedNodeEnvironmentFlags não fazem nada e falharão silenciosamente.

Se o Node.js foi compilado sem suporte a NODE_OPTIONS (mostrado em process.config), process.allowedNodeEnvironmentFlags conterá o que teria sido permitido.

`process.arch`

Adicionado em: v0.5.0

<string>

A arquitetura da CPU do sistema operacional para o qual o binário do Node.js foi compilado. Os valores possíveis são: 'arm', 'arm64', 'ia32', 'loong64', 'mips', 'mipsel', 'ppc', 'ppc64', 'riscv64', 's390', 's390x' e 'x64'.

ESMCJS

import { arch } from 'node:process';

console.log(`A arquitetura deste processador é ${arch}`);

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

console.log(`A arquitetura deste processador é ${arch}`);

`process.argv`

Adicionado em: v0.1.27

<string[]>

A propriedade process.argv retorna um array contendo os argumentos de linha de comando passados quando o processo Node.js foi iniciado. O primeiro elemento será process.execPath. Consulte process.argv0 se o acesso ao valor original de argv[0] for necessário. O segundo elemento será o caminho para o arquivo JavaScript que está sendo executado. Os elementos restantes serão quaisquer argumentos adicionais de linha de comando.

Por exemplo, assumindo o seguinte script para process-args.js:

ESMCJS

import { argv } from 'node:process';

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

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

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

Iniciando o processo Node.js como:

bash

node process-args.js one two=three four

Geraria a saída:

text

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

`process.argv0`

Adicionado em: v6.4.0

<string>

A propriedade process.argv0 armazena uma cópia somente leitura do valor original de argv[0] passado quando o Node.js é iniciado.

bash

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

`process.channel`

[Histórico]

Versão	Mudanças
v14.0.0	O objeto não expõe mais acidentalmente vinculações nativas de C++.
v7.1.0	Adicionado em: v7.1.0

<Object>

Se o processo Node.js foi gerado com um canal IPC (consulte a documentação de Processo Filho), a propriedade process.channel é uma referência ao canal IPC. Se não existir um canal IPC, esta propriedade será undefined.

`process.channel.ref()`

Adicionado em: v7.1.0

Este método faz com que o canal IPC mantenha o loop de eventos do processo em execução se .unref() tiver sido chamado antes.

Normalmente, isso é gerenciado através do número de listeners 'disconnect' e 'message' no objeto process. No entanto, este método pode ser usado para solicitar explicitamente um comportamento específico.

`process.channel.unref()`

Adicionado em: v7.1.0

Este método faz com que o canal IPC não mantenha o loop de eventos do processo em execução e permite que ele termine mesmo enquanto o canal está aberto.

`process.chdir(directory)`

Adicionado em: v0.1.17

directory <string>

O método process.chdir() altera o diretório de trabalho atual do processo Node.js ou lança uma exceção se isso falhar (por exemplo, se o directory especificado não existir).

ESMCJS

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

console.log(`Diretório inicial: ${cwd()}`);
try {
  chdir('/tmp');
  console.log(`Novo diretório: ${cwd()}`);
} catch (err) {
  console.error(`chdir: ${err}`);
}

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

console.log(`Diretório inicial: ${cwd()}`);
try {
  chdir('/tmp');
  console.log(`Novo diretório: ${cwd()}`);
} catch (err) {
  console.error(`chdir: ${err}`);
}

Este recurso não está disponível em threads Worker.

`process.config`

[Histórico]

Versão	Mudanças
v19.0.0	O objeto `process.config` agora está congelado.
v16.0.0	Modificar process.config foi depreciado.
v0.7.7	Adicionado em: v0.7.7

<Objeto>

A propriedade process.config retorna um Objeto congelado contendo a representação JavaScript das opções de configuração usadas para compilar o executável Node.js atual. Isso é o mesmo que o arquivo config.gypi que foi produzido ao executar o script ./configure.

Um exemplo da possível saída se parece com:

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

`process.connected`

Adicionado em: v0.7.2

<booleano>

Se o processo Node.js for gerado com um canal IPC (veja a documentação de Processo Filho e Cluster), a propriedade process.connected retornará true enquanto o canal IPC estiver conectado e retornará false após process.disconnect() ser chamado.

Uma vez que process.connected é false, não é mais possível enviar mensagens pelo canal IPC usando process.send().

`process.constrainedMemory()`

[Histórico]

Versão	Mudanças
v22.0.0, v20.13.0	Valor de retorno alinhado com `uv_get_constrained_memory`.
v19.6.0, v18.15.0	Adicionado em: v19.6.0, v18.15.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

<número>

Obtém a quantidade de memória disponível para o processo (em bytes) com base nos limites impostos pelo SO. Se não houver tal restrição, ou se a restrição for desconhecida, 0 é retornado.

Veja uv_get_constrained_memory para mais informações.

`process.availableMemory()`

Adicionado em: v22.0.0, v20.13.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

<number>

Obtém a quantidade de memória livre que ainda está disponível para o processo (em bytes).

Consulte uv_get_available_memory para obter mais informações.

`process.cpuUsage([previousValue])`

Adicionado em: v6.1.0

previousValue <Object> Um valor de retorno anterior da chamada process.cpuUsage()
Retorna: <Object>
- user <integer>
- system <integer>

O método process.cpuUsage() retorna o tempo de uso da CPU do usuário e do sistema do processo atual, em um objeto com propriedades user e system, cujos valores são valores de microssegundos (milionésimo de segundo). Esses valores medem o tempo gasto no código do usuário e do sistema, respectivamente, e podem acabar sendo maiores que o tempo decorrido real se vários núcleos da CPU estiverem executando o trabalho para este processo.

O resultado de uma chamada anterior para process.cpuUsage() pode ser passado como o argumento para a função, para obter uma leitura de diferença.

ESMCJS

import { cpuUsage } from 'node:process';

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

// simula o uso da CPU por 500 milissegundos
const now = Date.now();
while (Date.now() - now < 500);

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

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

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

// simula o uso da CPU por 500 milissegundos
const now = Date.now();
while (Date.now() - now < 500);

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

`process.cwd()`

Adicionado em: v0.1.8

Retorna: <string>

O método process.cwd() retorna o diretório de trabalho atual do processo Node.js.

ESMCJS

import { cwd } from 'node:process';

console.log(`Diretório atual: ${cwd()}`);

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

console.log(`Diretório atual: ${cwd()}`);

`process.debugPort`

Adicionado em: v0.7.2

<number>

A porta usada pelo depurador Node.js quando ativado.

ESMCJS

import process from 'node:process';

process.debugPort = 5858;

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

process.debugPort = 5858;

`process.disconnect()`

Adicionado em: v0.7.2

Se o processo Node.js for gerado com um canal IPC (veja a documentação de Processo Filho e Cluster), o método process.disconnect() fechará o canal IPC para o processo pai, permitindo que o processo filho saia normalmente quando não houver outras conexões o mantendo ativo.

O efeito de chamar process.disconnect() é o mesmo que chamar ChildProcess.disconnect() do processo pai.

Se o processo Node.js não foi gerado com um canal IPC, process.disconnect() será undefined.

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

[Histórico]

Versão	Mudanças
v9.0.0	Adicionado suporte para o argumento `flags`.
v0.1.16	Adicionado em: v0.1.16

module <Object>
filename <string>
flags <os.constants.dlopen> Padrão: os.constants.dlopen.RTLD_LAZY

O método process.dlopen() permite carregar dinamicamente objetos compartilhados. É usado principalmente por require() para carregar Addons C++, e não deve ser usado diretamente, exceto em casos especiais. Em outras palavras, require() deve ser preferido em vez de process.dlopen() a menos que existam razões específicas, como flags dlopen personalizadas ou carregamento de módulos ES.

O argumento flags é um inteiro que permite especificar o comportamento dlopen. Veja a documentação os.constants.dlopen para detalhes.

Um requisito importante ao chamar process.dlopen() é que a instância module deve ser passada. As funções exportadas pelo Addon C++ são então acessíveis via module.exports.

O exemplo abaixo mostra como carregar um Addon C++, nomeado local.node, que exporta uma função foo. Todos os símbolos são carregados antes que a chamada retorne, passando a constante RTLD_NOW. Neste exemplo, a constante é considerada disponível.

ESMCJS

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

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

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

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

`process.emitWarning(warning[, options])`

Adicionado em: v8.0.0

warning <string> | <Error> O aviso a ser emitido.
options <Object>
- type <string> Quando warning é uma String, type é o nome a ser usado para o tipo de aviso que está sendo emitido. Padrão: 'Warning'.
- code <string> Um identificador único para a instância de aviso que está sendo emitida.
- ctor <Function> Quando warning é uma String, ctor é uma função opcional usada para limitar o rastreamento de pilha gerado. Padrão: process.emitWarning.
- detail <string> Texto adicional para incluir com o erro.

O método process.emitWarning() pode ser usado para emitir avisos de processo personalizados ou específicos do aplicativo. Estes podem ser ouvidos adicionando um manipulador ao evento 'warning'.

ESMCJS

import { emitWarning } from 'node:process';

// Emitir um aviso com um código e detalhes adicionais.
emitWarning('Something happened!', {
  code: 'MY_WARNING',
  detail: 'This is some additional information',
});
// Emite:
// (node:56338) [MY_WARNING] Warning: Something happened!
// This is some additional information

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

// Emitir um aviso com um código e detalhes adicionais.
emitWarning('Something happened!', {
  code: 'MY_WARNING',
  detail: 'This is some additional information',
});
// Emite:
// (node:56338) [MY_WARNING] Warning: Something happened!
// This is some additional information

Neste exemplo, um objeto Error é gerado internamente por process.emitWarning() e passado para o manipulador de 'warning'.

ESMCJS

import process from 'node:process';

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

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

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

Se warning for passado como um objeto Error, o argumento options será ignorado.

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

Adicionado em: v6.0.0

warning <string> | <Error> O aviso a ser emitido.
type <string> Quando warning é uma String, type é o nome a ser usado para o tipo de aviso que está sendo emitido. Padrão: 'Warning'.
code <string> Um identificador único para a instância de aviso que está sendo emitida.
ctor <Function> Quando warning é uma String, ctor é uma função opcional usada para limitar o stack trace gerado. Padrão: process.emitWarning.

O método process.emitWarning() pode ser usado para emitir avisos de processo personalizados ou específicos do aplicativo. Eles podem ser ouvidos adicionando um manipulador ao evento 'warning'.

ESMCJS

import { emitWarning } from 'node:process';

// Emitir um aviso usando uma string.
emitWarning('Aconteceu algo!');
// Emite: (node: 56338) Warning: Aconteceu algo!

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

// Emitir um aviso usando uma string.
emitWarning('Aconteceu algo!');
// Emite: (node: 56338) Warning: Aconteceu algo!

ESMCJS

import { emitWarning } from 'node:process';

// Emitir um aviso usando uma string e um tipo.
emitWarning('Aconteceu algo!', 'AvisoPersonalizado');
// Emite: (node:56338) AvisoPersonalizado: Aconteceu algo!

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

// Emitir um aviso usando uma string e um tipo.
emitWarning('Aconteceu algo!', 'AvisoPersonalizado');
// Emite: (node:56338) AvisoPersonalizado: Aconteceu algo!

ESMCJS

import { emitWarning } from 'node:process';

emitWarning('Aconteceu algo!', 'AvisoPersonalizado', 'WARN001');
// Emite: (node:56338) [WARN001] AvisoPersonalizado: Aconteceu algo!

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

process.emitWarning('Aconteceu algo!', 'AvisoPersonalizado', 'WARN001');
// Emite: (node:56338) [WARN001] AvisoPersonalizado: Aconteceu algo!

Em cada um dos exemplos anteriores, um objeto Error é gerado internamente por process.emitWarning() e passado para o manipulador de 'warning'.

ESMCJS

import process from 'node:process';

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

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

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

Se warning for passado como um objeto Error, ele será passado para o manipulador de eventos 'warning' sem modificação (e os argumentos opcionais type, code e ctor serão ignorados):

ESMCJS

import { emitWarning } from 'node:process';

// Emitir um aviso usando um objeto Error.
const myWarning = new Error('Aconteceu algo!');
// Use a propriedade name do Error para especificar o nome do tipo
myWarning.name = 'AvisoPersonalizado';
myWarning.code = 'WARN001';

emitWarning(myWarning);
// Emite: (node:56338) [WARN001] AvisoPersonalizado: Aconteceu algo!

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

// Emitir um aviso usando um objeto Error.
const myWarning = new Error('Aconteceu algo!');
// Use a propriedade name do Error para especificar o nome do tipo
myWarning.name = 'AvisoPersonalizado';
myWarning.code = 'WARN001';

emitWarning(myWarning);
// Emite: (node:56338) [WARN001] AvisoPersonalizado: Aconteceu algo!

Um TypeError é lançado se warning for qualquer coisa além de uma string ou objeto Error.

Embora os avisos de processo usem objetos Error, o mecanismo de aviso de processo não é um substituto para os mecanismos normais de tratamento de erros.

O seguinte tratamento adicional é implementado se o type de aviso for 'DeprecationWarning':

Se o sinalizador de linha de comando --throw-deprecation for usado, o aviso de obsolescência será lançado como uma exceção em vez de ser emitido como um evento.
Se o sinalizador de linha de comando --no-deprecation for usado, o aviso de obsolescência será suprimido.
Se o sinalizador de linha de comando --trace-deprecation for usado, o aviso de obsolescência será impresso em stderr juntamente com o stack trace completo.

Evitando avisos duplicados

Como prática recomendada, os avisos devem ser emitidos apenas uma vez por processo. Para fazer isso, coloque o emitWarning() atrás de um booleano.

ESMCJS

import { emitWarning } from 'node:process';

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

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

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

`process.env`

[Histórico]

Versão	Mudanças
v11.14.0	As threads de Worker agora usarão uma cópia do `process.env` da thread pai por padrão, configurável por meio da opção `env` do construtor `Worker`.
v10.0.0	A conversão implícita do valor da variável para string está obsoleta.
v0.1.27	Adicionado em: v0.1.27

<Object>

A propriedade process.env retorna um objeto contendo o ambiente do usuário. Consulte environ(7).

Um exemplo desse objeto se parece com:

{
  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'
}

É possível modificar este objeto, mas tais modificações não serão refletidas fora do processo Node.js ou (a menos que explicitamente solicitado) para outras threads Worker. Em outras palavras, o exemplo a seguir não funcionaria:

bash

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

Enquanto o seguinte irá:

ESMCJS

import { env } from 'node:process';

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

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

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

Atribuir uma propriedade em process.env converterá implicitamente o valor em uma string. Este comportamento está obsoleto. As versões futuras do Node.js podem lançar um erro quando o valor não for uma string, número ou booleano.

ESMCJS

import { env } from 'node:process';

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

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

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

Use delete para excluir uma propriedade de process.env.

ESMCJS

import { env } from 'node:process';

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

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

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

Em sistemas operacionais Windows, as variáveis de ambiente não diferenciam maiúsculas de minúsculas.

ESMCJS

import { env } from 'node:process';

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

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

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

A menos que especificado explicitamente ao criar uma instância Worker, cada thread Worker tem sua própria cópia de process.env, com base no process.env de sua thread pai, ou o que foi especificado como a opção env para o construtor Worker. As alterações em process.env não serão visíveis nas threads Worker, e somente a thread principal pode fazer alterações que são visíveis para o sistema operacional ou para complementos nativos. No Windows, uma cópia de process.env em uma instância Worker opera de forma que diferencia maiúsculas de minúsculas, ao contrário da thread principal.

`process.execArgv`

Adicionado em: v0.7.7

<string[]>

A propriedade process.execArgv retorna o conjunto de opções de linha de comando específicas do Node.js passadas quando o processo do Node.js foi iniciado. Essas opções não aparecem no array retornado pela propriedade process.argv e não incluem o executável do Node.js, o nome do script ou quaisquer opções após o nome do script. Essas opções são úteis para gerar processos filho com o mesmo ambiente de execução do pai.

bash

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

Resulta em process.execArgv:

json

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

E process.argv:

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

Consulte o construtor Worker para obter o comportamento detalhado das threads worker com esta propriedade.

`process.execPath`

Adicionado em: v0.1.100

<string>

A propriedade process.execPath retorna o nome do caminho absoluto do executável que iniciou o processo do Node.js. Links simbólicos, se houver, são resolvidos.

'/usr/local/bin/node'

`process.exit([code])`

[Histórico]

Versão	Alterações
v20.0.0	Aceita apenas um código do tipo number ou do tipo string se representar um inteiro.
v0.1.13	Adicionado em: v0.1.13

code <integer> | <string> | <null> | <undefined> O código de saída. Para o tipo string, apenas strings inteiras (por exemplo, '1') são permitidas. Padrão: 0.

O método process.exit() instrui o Node.js a encerrar o processo de forma síncrona com um status de saída de code. Se code for omitido, exit usará o código 'success' 0 ou o valor de process.exitCode se ele tiver sido definido. O Node.js não será encerrado até que todos os listeners de evento 'exit' sejam chamados.

Para sair com um código de 'failure':

ESMCJS

import { exit } from 'node:process';

exit(1);

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

exit(1);

O shell que executou o Node.js deve ver o código de saída como 1.

Chamar process.exit() forçará o processo a sair o mais rápido possível, mesmo que ainda haja operações assíncronas pendentes que ainda não foram concluídas totalmente, incluindo operações de E/S para process.stdout e process.stderr.

Na maioria das situações, não é realmente necessário chamar process.exit() explicitamente. O processo do Node.js será encerrado por conta própria se não houver trabalho adicional pendente no loop de eventos. A propriedade process.exitCode pode ser definida para informar ao processo qual código de saída usar quando o processo for encerrado normalmente.

Por exemplo, o exemplo a seguir ilustra um uso incorreto do método process.exit() que pode levar ao truncamento e perda de dados impressos em stdout:

ESMCJS

import { exit } from 'node:process';

// Este é um exemplo do que *não* fazer:
if (someConditionNotMet()) {
  printUsageToStdout();
  exit(1);
}

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

// Este é um exemplo do que *não* fazer:
if (someConditionNotMet()) {
  printUsageToStdout();
  exit(1);
}

A razão pela qual isso é problemático é porque as gravações em process.stdout no Node.js são às vezes assíncronas e podem ocorrer em vários ticks do loop de eventos do Node.js. Chamar process.exit(), no entanto, força o processo a sair antes que essas gravações adicionais em stdout possam ser executadas.

Em vez de chamar process.exit() diretamente, o código deve definir process.exitCode e permitir que o processo saia naturalmente, evitando agendar qualquer trabalho adicional para o loop de eventos:

ESMCJS

import process from 'node:process';

// Como definir corretamente o código de saída, permitindo
// que o processo saia normalmente.
if (someConditionNotMet()) {
  printUsageToStdout();
  process.exitCode = 1;
}

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

// Como definir corretamente o código de saída, permitindo
// que o processo saia normalmente.
if (someConditionNotMet()) {
  printUsageToStdout();
  process.exitCode = 1;
}

Se for necessário encerrar o processo do Node.js devido a uma condição de erro, lançar um erro não capturado e permitir que o processo seja encerrado de acordo é mais seguro do que chamar process.exit().

Em threads Worker, esta função interrompe a thread atual em vez do processo atual.

`process.exitCode`

[Histórico]

Versão	Mudanças
v20.0.0	Aceita apenas um código do tipo number, ou do tipo string se representar um inteiro.
v0.11.8	Adicionado em: v0.11.8

<integer> | <string> | <null> | <undefined> O código de saída. Para o tipo string, apenas strings de inteiros (por exemplo, '1') são permitidas. Padrão: undefined.

Um número que será o código de saída do processo, quando o processo sair normalmente ou for encerrado por meio de process.exit() sem especificar um código.

Especificar um código para process.exit(code) substituirá qualquer configuração anterior de process.exitCode.

`process.features.cached_builtins`

Adicionado em: v12.0.0

<boolean>

Um valor booleano que é true se a versão atual do Node.js estiver armazenando em cache os módulos integrados.

`process.features.debug`

Adicionado em: v0.5.5

<boolean>

Um valor booleano que é true se a versão atual do Node.js for uma versão de depuração.

`process.features.inspector`

Adicionado em: v11.10.0

<boolean>

Um valor booleano que é true se a versão atual do Node.js incluir o inspetor.

`process.features.ipv6`

Adicionado em: v0.5.3

Obsoleto desde: v23.4.0

[Estável: 0 - Obsoleto]

Estável: 0 Estabilidade: 0 - Obsoleto. Esta propriedade é sempre verdadeira e quaisquer verificações baseadas nela são redundantes.

<boolean>

Um valor booleano que é true se a versão atual do Node.js incluir suporte para IPv6.

Como todas as versões do Node.js têm suporte para IPv6, esse valor é sempre true.

`process.features.require_module`

Adicionado em: v23.0.0

<boolean>

Um valor booleano que é true se a build atual do Node.js suporta carregar módulos ECMAScript usando require().

`process.features.tls`

Adicionado em: v0.5.3

<boolean>

Um valor booleano que é true se a build atual do Node.js inclui suporte para TLS.

`process.features.tls_alpn`

Adicionado em: v4.8.0

Obsoleto desde: v23.4.0

[Estável: 0 - Obsoleto]

Estável: 0 Estabilidade: 0 - Obsoleto. Use process.features.tls em vez disso.

<boolean>

Um valor booleano que é true se a build atual do Node.js inclui suporte para ALPN em TLS.

No Node.js 11.0.0 e versões posteriores, as dependências do OpenSSL apresentam suporte incondicional ao ALPN. Portanto, esse valor é idêntico ao de process.features.tls.

`process.features.tls_ocsp`

Adicionado em: v0.11.13

Obsoleto desde: v23.4.0

[Estável: 0 - Obsoleto]

Estável: 0 Estabilidade: 0 - Obsoleto. Use process.features.tls em vez disso.

<boolean>

Um valor booleano que é true se a build atual do Node.js inclui suporte para OCSP em TLS.

No Node.js 11.0.0 e versões posteriores, as dependências do OpenSSL apresentam suporte incondicional ao OCSP. Portanto, esse valor é idêntico ao de process.features.tls.

`process.features.tls_sni`

Adicionado em: v0.5.3

Obsoleto desde: v23.4.0

[Estável: 0 - Obsoleto]

Estável: 0 Estabilidade: 0 - Obsoleto. Use process.features.tls em vez disso.

<boolean>

Um valor booleano que é true se a build atual do Node.js inclui suporte para SNI em TLS.

No Node.js 11.0.0 e versões posteriores, as dependências do OpenSSL apresentam suporte incondicional ao SNI. Portanto, esse valor é idêntico ao de process.features.tls.

`process.features.typescript`

Adicionado em: v23.0.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1.1 - Desenvolvimento Ativo

<boolean> | <string>

Um valor que é "strip" se o Node.js for executado com --experimental-strip-types, "transform" se o Node.js for executado com --experimental-transform-types e false caso contrário.

`process.features.uv`

Adicionado em: v0.5.3

Obsoleto desde: v23.4.0

[Estável: 0 - Obsoleto]

Estável: 0 Estabilidade: 0 - Obsoleto. Esta propriedade é sempre verdadeira, e quaisquer verificações baseadas nela são redundantes.

<boolean>

Um valor booleano que é true se a construção atual do Node.js inclui suporte para libuv.

Como não é possível construir o Node.js sem libuv, este valor é sempre true.

`process.finalization.register(ref, callback)`

Adicionado em: v22.5.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1.1 - Desenvolvimento Ativo

ref <Object> | <Function> A referência ao recurso que está sendo rastreado.
callback <Function> A função de retorno de chamada a ser chamada quando o recurso é finalizado.
- ref <Object> | <Function> A referência ao recurso que está sendo rastreado.
- event <string> O evento que acionou a finalização. O padrão é 'exit'.

Esta função registra um retorno de chamada a ser chamado quando o processo emite o evento exit se o objeto ref não foi coletado como lixo. Se o objeto ref foi coletado como lixo antes que o evento exit seja emitido, o retorno de chamada será removido do registro de finalização e não será chamado na saída do processo.

Dentro do retorno de chamada, você pode liberar os recursos alocados pelo objeto ref. Esteja ciente de que todas as limitações aplicadas ao evento beforeExit também são aplicadas à função callback, o que significa que existe a possibilidade de que o retorno de chamada não seja chamado em circunstâncias especiais.

A ideia desta função é ajudá-lo a liberar recursos quando o processo começar a sair, mas também permitir que o objeto seja coletado como lixo se não estiver mais sendo usado.

Por exemplo: você pode registrar um objeto que contém um buffer, você quer ter certeza de que o buffer é liberado quando o processo sai, mas se o objeto for coletado como lixo antes da saída do processo, não precisamos mais liberar o buffer, então, neste caso, apenas removemos o retorno de chamada do registro de finalização.

CJSESM

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

// Por favor, certifique-se de que a função passada para finalization.register()
// não cria um fechamento em torno de objetos desnecessários.
function onFinalize(obj, event) {
  // Você pode fazer o que quiser com o objeto
  obj.dispose();
}

function setup() {
  // Este objeto pode ser seguramente coletado como lixo,
  // e a função de desligamento resultante não será chamada.
  // Não há vazamentos.
  const myDisposableObject = {
    dispose() {
      // Libere seus recursos de forma síncrona
    },
  };

  finalization.register(myDisposableObject, onFinalize);
}

setup();

import { finalization } from 'node:process';

// Por favor, certifique-se de que a função passada para finalization.register()
// não cria um fechamento em torno de objetos desnecessários.
function onFinalize(obj, event) {
  // Você pode fazer o que quiser com o objeto
  obj.dispose();
}

function setup() {
  // Este objeto pode ser seguramente coletado como lixo,
  // e a função de desligamento resultante não será chamada.
  // Não há vazamentos.
  const myDisposableObject = {
    dispose() {
      // Libere seus recursos de forma síncrona
    },
  };

  finalization.register(myDisposableObject, onFinalize);
}

setup();

O código acima depende das seguintes premissas:

funções de seta são evitadas
funções regulares são recomendadas para estarem dentro do contexto global (raiz)

Funções regulares poderiam referenciar o contexto onde o obj vive, tornando o obj não coletável como lixo.

Funções de seta manterão o contexto anterior. Considere, por exemplo:

class Test {
  constructor() {
    finalization.register(this, (ref) => ref.dispose());

    // Mesmo algo assim é altamente desencorajado
    // finalization.register(this, () => this.dispose());
  }
  dispose() {}
}

É muito improvável (não impossível) que este objeto seja coletado como lixo, mas se não for, dispose será chamado quando process.exit for chamado.

Tenha cuidado e evite depender deste recurso para a eliminação de recursos críticos, pois não é garantido que o retorno de chamada seja chamado em todas as circunstâncias.

`process.finalization.registerBeforeExit(ref, callback)`

Adicionado em: v22.5.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1.1 - Desenvolvimento Ativo

ref <Object> | <Function> A referência ao recurso que está sendo rastreado.
callback <Function> A função de callback a ser chamada quando o recurso for finalizado.
- ref <Object> | <Function> A referência ao recurso que está sendo rastreado.
- event <string> O evento que acionou a finalização. O padrão é 'beforeExit'.

Esta função se comporta exatamente como o register, exceto que o callback será chamado quando o processo emitir o evento beforeExit se o objeto ref não foi coletado pelo garbage collector.

Esteja ciente de que todas as limitações aplicadas ao evento beforeExit também são aplicadas à função callback, isso significa que existe a possibilidade de que o callback não seja chamado em circunstâncias especiais.

`process.finalization.unregister(ref)`

Adicionado em: v22.5.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1.1 - Desenvolvimento Ativo

ref <Object> | <Function> A referência ao recurso que foi registrado anteriormente.

Esta função remove o registro do objeto do registro de finalização, para que o callback não seja mais chamado.

CJSESM

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

// Por favor, certifique-se de que a função passada para finalization.register()
// não crie um closure em torno de objetos desnecessários.
function onFinalize(obj, event) {
  // Você pode fazer o que quiser com o objeto
  obj.dispose();
}

function setup() {
  // Este objeto pode ser seguramente coletado pelo garbage collector,
  // e a função de desligamento resultante não será chamada.
  // Não há vazamentos.
  const myDisposableObject = {
    dispose() {
      // Libere seus recursos sincronamente
    },
  };

  finalization.register(myDisposableObject, onFinalize);

  // Faça algo

  myDisposableObject.dispose();
  finalization.unregister(myDisposableObject);
}

setup();

import { finalization } from 'node:process';

// Por favor, certifique-se de que a função passada para finalization.register()
// não crie um closure em torno de objetos desnecessários.
function onFinalize(obj, event) {
  // Você pode fazer o que quiser com o objeto
  obj.dispose();
}

function setup() {
  // Este objeto pode ser seguramente coletado pelo garbage collector,
  // e a função de desligamento resultante não será chamada.
  // Não há vazamentos.
  const myDisposableObject = {
    dispose() {
      // Libere seus recursos sincronamente
    },
  };

  // Por favor, certifique-se de que a função passada para finalization.register()
  // não crie um closure em torno de objetos desnecessários.
  function onFinalize(obj, event) {
    // Você pode fazer o que quiser com o objeto
    obj.dispose();
  }

  finalization.register(myDisposableObject, onFinalize);

  // Faça algo

  myDisposableObject.dispose();
  finalization.unregister(myDisposableObject);
}

setup();

`process.getActiveResourcesInfo()`

Adicionado em: v17.3.0, v16.14.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

Retorna: <string[]>

O método process.getActiveResourcesInfo() retorna um array de strings contendo os tipos dos recursos ativos que estão atualmente mantendo o loop de eventos ativo.

ESMCJS

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

console.log('Antes:', getActiveResourcesInfo());
setTimeout(() => {}, 1000);
console.log('Depois:', getActiveResourcesInfo());
// Imprime:
//   Antes: [ 'CloseReq', 'TTYWrap', 'TTYWrap', 'TTYWrap' ]
//   Depois: [ 'CloseReq', 'TTYWrap', 'TTYWrap', 'TTYWrap', 'Timeout' ]

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

console.log('Antes:', getActiveResourcesInfo());
setTimeout(() => {}, 1000);
console.log('Depois:', getActiveResourcesInfo());
// Imprime:
//   Antes: [ 'TTYWrap', 'TTYWrap', 'TTYWrap' ]
//   Depois: [ 'TTYWrap', 'TTYWrap', 'TTYWrap', 'Timeout' ]

`process.getBuiltinModule(id)`

Adicionado em: v22.3.0, v20.16.0

id <string> ID do módulo integrado que está sendo solicitado.
Retorna: <Object> | <undefined>

process.getBuiltinModule(id) fornece uma maneira de carregar módulos integrados em uma função globalmente disponível. Módulos ES que precisam suportar outros ambientes podem usá-lo para carregar condicionalmente um módulo integrado do Node.js quando executado no Node.js, sem ter que lidar com o erro de resolução que pode ser lançado por import em um ambiente não Node.js ou ter que usar import() dinâmico, que transforma o módulo em um módulo assíncrono ou transforma uma API síncrona em uma assíncrona.

if (globalThis.process?.getBuiltinModule) {
  // Executar no Node.js, usar o módulo fs do Node.js.
  const fs = globalThis.process.getBuiltinModule('fs');
  // Se `require()` for necessário para carregar módulos de usuário, use createRequire()
  const module = globalThis.process.getBuiltinModule('module');
  const require = module.createRequire(import.meta.url);
  const foo = require('foo');
}

Se id especificar um módulo integrado disponível no processo Node.js atual, o método process.getBuiltinModule(id) retorna o módulo integrado correspondente. Se id não corresponder a nenhum módulo integrado, undefined é retornado.

process.getBuiltinModule(id) aceita IDs de módulos integrados que são reconhecidos por module.isBuiltin(id). Alguns módulos integrados devem ser carregados com o prefixo node:, consulte módulos integrados com prefixo node: obrigatório. As referências retornadas por process.getBuiltinModule(id) sempre apontam para o módulo integrado correspondente a id, mesmo que os usuários modifiquem require.cache para que require(id) retorne outra coisa.

`process.getegid()`

Adicionado em: v2.0.0

O método process.getegid() retorna a identidade de grupo efetiva numérica do processo Node.js. (Veja getegid(2).)

ESMCJS

import process from 'node:process';

if (process.getegid) {
  console.log(`GID atual: ${process.getegid()}`);
}

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

if (process.getegid) {
  console.log(`GID atual: ${process.getegid()}`);
}

Esta função está disponível apenas em plataformas POSIX (ou seja, não Windows ou Android).

`process.geteuid()`

Adicionado em: v2.0.0

Retorna: <Object>

O método process.geteuid() retorna a identidade de usuário efetiva numérica do processo. (Veja geteuid(2).)

ESMCJS

import process from 'node:process';

if (process.geteuid) {
  console.log(`UID atual: ${process.geteuid()}`);
}

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

if (process.geteuid) {
  console.log(`UID atual: ${process.geteuid()}`);
}

Esta função está disponível apenas em plataformas POSIX (ou seja, não Windows ou Android).

`process.getgid()`

Adicionado em: v0.1.31

Retorna: <Object>

O método process.getgid() retorna a identidade de grupo numérica do processo. (Veja getgid(2).)

ESMCJS

import process from 'node:process';

if (process.getgid) {
  console.log(`GID atual: ${process.getgid()}`);
}

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

if (process.getgid) {
  console.log(`GID atual: ${process.getgid()}`);
}

Esta função está disponível apenas em plataformas POSIX (ou seja, não Windows ou Android).

`process.getgroups()`

Adicionado em: v0.9.4

Retorna: <integer[]>

O método process.getgroups() retorna um array com os IDs de grupo suplementares. O POSIX não especifica se o ID de grupo efetivo está incluído, mas o Node.js garante que esteja sempre.

ESMCJS

import process from 'node:process';

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

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

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

Esta função está disponível apenas em plataformas POSIX (ou seja, não Windows ou Android).

`process.getuid()`

Adicionado em: v0.1.28

Retorna: <integer>

O método process.getuid() retorna a identidade numérica do usuário do processo. (Consulte getuid(2).)

ESMCJS

import process from 'node:process';

if (process.getuid) {
  console.log(`UID atual: ${process.getuid()}`);
}

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

if (process.getuid) {
  console.log(`UID atual: ${process.getuid()}`);
}

Esta função está disponível apenas em plataformas POSIX (ou seja, não Windows ou Android).

`process.hasUncaughtExceptionCaptureCallback()`

Adicionado em: v9.3.0

Retorna: <boolean>

Indica se um callback foi definido usando process.setUncaughtExceptionCaptureCallback().

`process.hrtime([time])`

Adicionado em: v0.7.6

[Estável: 3 - Legado]

Estável: 3 Estabilidade: 3 - Legado. Use process.hrtime.bigint() em vez disso.

time <integer[]> O resultado de uma chamada anterior para process.hrtime()
Retorna: <integer[]>

Esta é a versão legada de process.hrtime.bigint() antes de bigint ser introduzido em JavaScript.

O método process.hrtime() retorna o tempo real de alta resolução atual em um Array de tupla [segundos, nanossegundos], onde nanossegundos é a parte restante do tempo real que não pode ser representada em precisão de segundos.

time é um parâmetro opcional que deve ser o resultado de uma chamada anterior de process.hrtime() para diferenciar com a hora atual. Se o parâmetro passado não for um Array de tupla, um TypeError será lançado. Passar um array definido pelo usuário em vez do resultado de uma chamada anterior para process.hrtime() levará a um comportamento indefinido.

Esses tempos são relativos a um tempo arbitrário no passado e não estão relacionados à hora do dia e, portanto, não estão sujeitos ao desvio do relógio. O uso principal é para medir o desempenho entre intervalos:

ESMCJS

import { hrtime } from 'node:process';

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

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

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

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

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

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

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

`process.hrtime.bigint()`

Adicionado em: v10.7.0

Retorna: <bigint>

A versão bigint do método process.hrtime() que retorna o tempo real de alta resolução atual em nanossegundos como um bigint.

Ao contrário de process.hrtime(), ele não suporta um argumento time adicional, pois a diferença pode ser calculada diretamente pela subtração dos dois bigints.

ESMCJS

import { hrtime } from 'node:process';

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

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

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

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

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

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

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

`process.initgroups(user, extraGroup)`

Adicionado em: v0.9.4

user <string> | <number> O nome de usuário ou identificador numérico.
extraGroup <string> | <number> Um nome de grupo ou identificador numérico.

O método process.initgroups() lê o arquivo /etc/group e inicializa a lista de acesso ao grupo, usando todos os grupos dos quais o usuário é membro. Esta é uma operação privilegiada que requer que o processo Node.js tenha acesso root ou a capacidade CAP_SETGID.

Tenha cuidado ao remover privilégios:

ESMCJS

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

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

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

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

Esta função está disponível apenas em plataformas POSIX (ou seja, não Windows ou Android). Este recurso não está disponível em threads Worker.

`process.kill(pid[, signal])`

Adicionado em: v0.0.6

pid <number> Um ID de processo
signal <string> | <number> O sinal a ser enviado, seja como uma string ou número. Padrão: 'SIGTERM'.

O método process.kill() envia o signal para o processo identificado por pid.

Nomes de sinal são strings como 'SIGINT' ou 'SIGHUP'. Consulte Eventos de Sinal e kill(2) para mais informações.

Este método lançará um erro se o pid de destino não existir. Como um caso especial, um sinal de 0 pode ser usado para testar a existência de um processo. As plataformas Windows lançarão um erro se o pid for usado para encerrar um grupo de processos.

Mesmo que o nome desta função seja process.kill(), ela é realmente apenas um remetente de sinal, como a chamada de sistema kill. O sinal enviado pode fazer algo diferente de encerrar o processo de destino.

ESMCJS

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

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

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

kill(process.pid, 'SIGHUP');

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

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

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

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

Quando SIGUSR1 é recebido por um processo Node.js, o Node.js iniciará o depurador. Consulte Eventos de Sinal.

`process.loadEnvFile(path)`

Adicionado em: v21.7.0, v20.12.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1.1 - Desenvolvimento ativo

path <string> | <URL> | <Buffer> | <undefined>. Padrão: './.env'

Carrega o arquivo .env em process.env. O uso de NODE_OPTIONS no arquivo .env não terá nenhum efeito no Node.js.

CJSESM

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

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

`process.mainModule`

Adicionado em: v0.1.17

Obsoleto desde: v14.0.0

[Estável: 0 - Obsoleto]

Estável: 0 Estabilidade: 0 - Obsoleto: Use require.main em vez disso.

<Object>

A propriedade process.mainModule fornece uma maneira alternativa de recuperar require.main. A diferença é que, se o módulo principal mudar em tempo de execução, require.main ainda pode se referir ao módulo principal original em módulos que foram requisitados antes da ocorrência da mudança. Geralmente, é seguro presumir que os dois se referem ao mesmo módulo.

Como com require.main, process.mainModule será undefined se não houver script de entrada.

`process.memoryUsage()`

[Histórico]

Versão	Alterações
v13.9.0, v12.17.0	Adicionado `arrayBuffers` ao objeto retornado.
v7.2.0	Adicionado `external` ao objeto retornado.
v0.1.16	Adicionado em: v0.1.16

Retorna: <Object>
- rss <integer>
- heapTotal <integer>
- heapUsed <integer>
- external <integer>
- arrayBuffers <integer>

Retorna um objeto descrevendo o uso de memória do processo Node.js medido em bytes.

ESMCJS

import { memoryUsage } from 'node:process';

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

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

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

heapTotal e heapUsed referem-se ao uso de memória do V8.
external refere-se ao uso de memória de objetos C++ vinculados a objetos JavaScript gerenciados pelo V8.
rss, Resident Set Size, é a quantidade de espaço ocupada na memória principal (que é um subconjunto da memória total alocada) para o processo, incluindo todos os objetos e códigos C++ e JavaScript.
arrayBuffers refere-se à memória alocada para ArrayBuffers e SharedArrayBuffers, incluindo todos os Buffers Node.js. Isso também está incluído no valor external. Quando o Node.js é usado como uma biblioteca incorporada, este valor pode ser 0 porque as alocações para ArrayBuffers podem não ser rastreadas nesse caso.

Ao usar threads Worker, rss será um valor válido para todo o processo, enquanto os outros campos se referirão apenas ao thread atual.

O método process.memoryUsage() itera sobre cada página para coletar informações sobre o uso da memória, o que pode ser lento dependendo das alocações de memória do programa.

`process.memoryUsage.rss()`

Adicionado em: v15.6.0, v14.18.0

Retorna: <integer>

O método process.memoryUsage.rss() retorna um inteiro representando o Resident Set Size (RSS) em bytes.

O Resident Set Size é a quantidade de espaço ocupada na memória principal (que é um subconjunto da memória total alocada) para o processo, incluindo todos os objetos e códigos C++ e JavaScript.

Este é o mesmo valor da propriedade rss fornecida por process.memoryUsage(), mas process.memoryUsage.rss() é mais rápido.

ESMCJS

import { memoryUsage } from 'node:process';

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

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

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

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

[Histórico]

Versão	Alterações
v22.7.0, v20.18.0	Alterou a estabilidade para Legado.
v18.0.0	Passar um callback inválido para o argumento `callback` agora lança `ERR_INVALID_ARG_TYPE` em vez de `ERR_INVALID_CALLBACK`.
v1.8.1	Argumentos adicionais após `callback` agora são suportados.
v0.1.26	Adicionado em: v0.1.26

[Estável: 3 - Legado]

Estável: 3 Estabilidade: 3 - Legado: Use queueMicrotask() em vez disso.

callback <Function>
...args <any> Argumentos adicionais para passar ao invocar o callback

process.nextTick() adiciona callback à "próxima fila de tick". Esta fila é totalmente esvaziada após a conclusão da operação atual na pilha JavaScript e antes que o loop de eventos possa continuar. É possível criar um loop infinito se alguém chamar recursivamente process.nextTick(). Consulte o guia Loop de Eventos para obter mais informações.

ESMCJS

import { nextTick } from 'node:process';

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

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

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

Isso é importante ao desenvolver APIs para dar aos usuários a oportunidade de atribuir manipuladores de eventos após a construção de um objeto, mas antes que qualquer E/S ocorra:

ESMCJS

import { nextTick } from 'node:process';

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

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

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

// thing.startDoingStuff() é chamado agora, não antes.

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

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

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

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

// thing.startDoingStuff() é chamado agora, não antes.

É muito importante que as APIs sejam 100% síncronas ou 100% assíncronas. Considere este exemplo:

// AVISO! NÃO USE! PERIGO RUIM E INSEGURO!
function maybeSync(arg, cb) {
  if (arg) {
    cb();
    return;
  }

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

Esta API é perigosa porque no caso a seguir:

const maybeTrue = Math.random() > 0.5;

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

bar();

Não está claro se foo() ou bar() serão chamados primeiro.

A seguinte abordagem é muito melhor:

ESMCJS

import { nextTick } from 'node:process';

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

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

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

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

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

Quando usar `queueMicrotask()` vs. `process.nextTick()`

A API queueMicrotask() é uma alternativa a process.nextTick() que também adia a execução de uma função usando a mesma fila de microtarefas usada para executar os manipuladores then, catch e finally de promessas resolvidas. Dentro do Node.js, toda vez que a "próxima fila de ticks" é esvaziada, a fila de microtarefas é esvaziada imediatamente depois.

ESMCJS

import { nextTick } from 'node:process';

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

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

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

Para a maioria dos casos de uso de userland, a API queueMicrotask() fornece um mecanismo portátil e confiável para adiar a execução que funciona em vários ambientes de plataforma JavaScript e deve ser preferido em relação a process.nextTick(). Em cenários simples, queueMicrotask() pode ser um substituto direto para process.nextTick().

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

Uma diferença notável entre as duas APIs é que process.nextTick() permite especificar valores adicionais que serão passados como argumentos para a função adiada quando ela for chamada. Atingir o mesmo resultado com queueMicrotask() requer o uso de um closure ou uma função vinculada:

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

Existem pequenas diferenças na forma como os erros gerados de dentro da próxima fila de ticks e da fila de microtarefas são tratados. Erros lançados dentro de um callback de microtarefa enfileirado devem ser tratados dentro do callback enfileirado quando possível. Se não forem, o manipulador de eventos process.on('uncaughtException') pode ser usado para capturar e tratar os erros.

Em caso de dúvida, a menos que as capacidades específicas de process.nextTick() sejam necessárias, use queueMicrotask().

`process.noDeprecation`

Adicionado em: v0.8.0

<boolean>

A propriedade process.noDeprecation indica se a flag --no-deprecation está definida no processo Node.js atual. Consulte a documentação para o 'warning' event e o método emitWarning() method para obter mais informações sobre o comportamento desta flag.

`process.permission`

Adicionado em: v20.0.0

<Object>

Esta API está disponível através da flag --permission.

process.permission é um objeto cujos métodos são usados para gerenciar permissões para o processo atual. Documentação adicional está disponível no Modelo de Permissão.

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

Adicionado em: v20.0.0

scope <string>
reference <string>
Retorna: <boolean>

Verifica se o processo é capaz de acessar o escopo e a referência fornecidos. Se nenhuma referência for fornecida, um escopo global é assumido, por exemplo, process.permission.has('fs.read') verificará se o processo tem TODAS as permissões de leitura do sistema de arquivos.

A referência tem um significado com base no escopo fornecido. Por exemplo, a referência quando o escopo é Sistema de Arquivos significa arquivos e pastas.

Os escopos disponíveis são:

fs - Todo o sistema de arquivos
fs.read - Operações de leitura do sistema de arquivos
fs.write - Operações de gravação do sistema de arquivos
child - Operações de geração de processos filhos
worker - Operação de geração de threads de worker

// Verifica se o processo tem permissão para ler o arquivo README
process.permission.has('fs.read', './README.md');
// Verifica se o processo tem operações de permissão de leitura
process.permission.has('fs.read');

`process.pid`

Adicionado em: v0.1.15

<integer>

A propriedade process.pid retorna o PID do processo.

ESMCJS

import { pid } from 'node:process';

console.log(`Este processo tem o PID ${pid}`);

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

console.log(`Este processo tem o PID ${pid}`);

`process.platform`

Adicionado em: v0.1.16

<string>

A propriedade process.platform retorna uma string que identifica a plataforma do sistema operacional para a qual o binário do Node.js foi compilado.

Atualmente, os valores possíveis são:

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

ESMCJS

import { platform } from 'node:process';

console.log(`Esta plataforma é ${platform}`);

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

console.log(`Esta plataforma é ${platform}`);

O valor 'android' também pode ser retornado se o Node.js for construído no sistema operacional Android. No entanto, o suporte ao Android no Node.js é experimental.

`process.ppid`

Adicionado em: v9.2.0, v8.10.0, v6.13.0

<integer>

A propriedade process.ppid retorna o PID do pai do processo atual.

ESMCJS

import { ppid } from 'node:process';

console.log(`O processo pai é pid ${ppid}`);

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

console.log(`O processo pai é pid ${ppid}`);

`process.release`

[Histórico]

Versão	Alterações
v4.2.0	A propriedade `lts` agora é suportada.
v3.0.0	Adicionado em: v3.0.0

<Object>

A propriedade process.release retorna um Object contendo metadados relacionados à versão atual, incluindo URLs para o tarball de origem e o tarball somente de cabeçalhos.

process.release contém as seguintes propriedades:

name <string> Um valor que sempre será 'node'.
sourceUrl <string> um URL absoluto apontando para um arquivo .tar.gz contendo o código-fonte da versão atual.
headersUrl <string> um URL absoluto apontando para um arquivo .tar.gz contendo apenas os arquivos de cabeçalho de origem para a versão atual. Este arquivo é significativamente menor que o arquivo de origem completo e pode ser usado para compilar complementos nativos do Node.js.
libUrl <string> | <undefined> um URL absoluto apontando para um arquivo node.lib que corresponde à arquitetura e versão da versão atual. Este arquivo é usado para compilar complementos nativos do Node.js. Esta propriedade está presente apenas em compilações do Windows do Node.js e estará ausente em todas as outras plataformas.
lts <string> | <undefined> um rótulo de string que identifica o rótulo LTS para esta versão. Esta propriedade existe apenas para versões LTS e é undefined para todos os outros tipos de versão, incluindo versões Current. Os valores válidos incluem os nomes de código da versão LTS (incluindo aqueles que não são mais suportados).
- 'Fermium' para a linha 14.x LTS a partir de 14.15.0.
- 'Gallium' para a linha 16.x LTS a partir de 16.13.0.
- 'Hydrogen' para a linha 18.x LTS a partir de 18.12.0. Para outros nomes de código da versão LTS, consulte Arquivo de Changelog do Node.js

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

Em compilações personalizadas de versões não lançadas da árvore de origem, apenas a propriedade name pode estar presente. Não se deve confiar na existência das propriedades adicionais.

`process.report`

[Histórico]

Versão	Mudanças
v13.12.0, v12.17.0	Esta API não é mais experimental.
v11.8.0	Adicionado em: v11.8.0

<Object>

process.report é um objeto cujos métodos são usados para gerar relatórios de diagnóstico para o processo atual. Documentação adicional está disponível na documentação do relatório.

`process.report.compact`

Adicionado em: v13.12.0, v12.17.0

<boolean>

Escreve relatórios em um formato compacto, JSON de linha única, mais facilmente consumível por sistemas de processamento de log do que o formato multi-linha padrão projetado para consumo humano.

ESMCJS

import { report } from 'node:process';

console.log(`Relatórios são compactos? ${report.compact}`);

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

console.log(`Relatórios são compactos? ${report.compact}`);

`process.report.directory`

[Histórico]

Versão	Mudanças
v13.12.0, v12.17.0	Esta API não é mais experimental.
v11.12.0	Adicionado em: v11.12.0

<string>

Diretório onde o relatório é gravado. O valor padrão é a string vazia, indicando que os relatórios são gravados no diretório de trabalho atual do processo Node.js.

ESMCJS

import { report } from 'node:process';

console.log(`O diretório do relatório é ${report.directory}`);

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

console.log(`O diretório do relatório é ${report.directory}`);

`process.report.filename`

[Histórico]

Versão	Mudanças
v13.12.0, v12.17.0	Esta API não é mais experimental.
v11.12.0	Adicionado em: v11.12.0

<string>

Nome do arquivo onde o relatório é gravado. Se definido como string vazia, o nome do arquivo de saída será composto por um timestamp, PID e número de sequência. O valor padrão é a string vazia.

Se o valor de process.report.filename for definido como 'stdout' ou 'stderr', o relatório será gravado no stdout ou stderr do processo, respectivamente.

ESMCJS

import { report } from 'node:process';

console.log(`O nome do arquivo do relatório é ${report.filename}`);

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

console.log(`O nome do arquivo do relatório é ${report.filename}`);

`process.report.getReport([err])`

[Histórico]

Versão	Mudanças
v13.12.0, v12.17.0	Esta API não é mais experimental.
v11.8.0	Adicionado em: v11.8.0

err <Error> Um erro personalizado usado para relatar o stack do JavaScript.
Retorna: <Object>

Retorna uma representação de Objeto JavaScript de um relatório de diagnóstico para o processo em execução. O stack trace do JavaScript do relatório é obtido de err, se presente.

ESMCJS

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

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

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

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

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

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

Documentação adicional está disponível na documentação do relatório.

`process.report.reportOnFatalError`

[Histórico]

Versão	Mudanças
v15.0.0, v14.17.0	Esta API não é mais experimental.
v11.12.0	Adicionado em: v11.12.0

<boolean>

Se true, um relatório de diagnóstico é gerado em erros fatais, como erros de falta de memória ou falhas em asserções C++.

ESMCJS

import { report } from 'node:process';

console.log(`Relatório em erro fatal: ${report.reportOnFatalError}`);

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

console.log(`Relatório em erro fatal: ${report.reportOnFatalError}`);

`process.report.reportOnSignal`

[Histórico]

Versão	Mudanças
v13.12.0, v12.17.0	Esta API não é mais experimental.
v11.12.0	Adicionado em: v11.12.0

<boolean>

Se true, um relatório de diagnóstico é gerado quando o processo recebe o sinal especificado por process.report.signal.

ESMCJS

import { report } from 'node:process';

console.log(`Relatório no sinal: ${report.reportOnSignal}`);

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

console.log(`Relatório no sinal: ${report.reportOnSignal}`);

`process.report.reportOnUncaughtException`

[Histórico]

Versão	Mudanças
v13.12.0, v12.17.0	Esta API não é mais experimental.
v11.12.0	Adicionado em: v11.12.0

<boolean>

Se true, um relatório de diagnóstico é gerado em uma exceção não capturada.

ESMCJS

import { report } from 'node:process';

console.log(`Relatório na exceção: ${report.reportOnUncaughtException}`);

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

console.log(`Relatório na exceção: ${report.reportOnUncaughtException}`);

`process.report.excludeEnv`

Adicionado em: v23.3.0

<boolean>

Se true, um relatório de diagnóstico é gerado sem as variáveis de ambiente.

`process.report.signal`

[Histórico]

Versão	Mudanças
v13.12.0, v12.17.0	Esta API não é mais experimental.
v11.12.0	Adicionado em: v11.12.0

<string>

O sinal usado para acionar a criação de um relatório de diagnóstico. O padrão é 'SIGUSR2'.

ESMCJS

import { report } from 'node:process';

console.log(`Sinal do relatório: ${report.signal}`);

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

console.log(`Sinal do relatório: ${report.signal}`);

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

[Histórico]

Versão	Mudanças
v13.12.0, v12.17.0	Esta API não é mais experimental.
v11.8.0	Adicionado em: v11.8.0

filename <string> Nome do arquivo onde o relatório é escrito. Este deve ser um caminho relativo, que será anexado ao diretório especificado em process.report.directory, ou o diretório de trabalho atual do processo Node.js, se não especificado.
err <Error> Um erro personalizado usado para relatar o stack do JavaScript.
Retorna: <string> Retorna o nome do arquivo do relatório gerado.

Escreve um relatório de diagnóstico em um arquivo. Se filename não for fornecido, o nome de arquivo padrão inclui a data, hora, PID e um número de sequência. O stack trace JavaScript do relatório é obtido de err, se presente.

Se o valor de filename for definido como 'stdout' ou 'stderr', o relatório é escrito para stdout ou stderr do processo, respectivamente.

ESMCJS

import { report } from 'node:process';

report.writeReport();

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

report.writeReport();

Documentação adicional está disponível na documentação do relatório.

`process.resourceUsage()`

Adicionado em: v12.6.0

Retorna: <Object> o uso de recursos para o processo atual. Todos esses valores vêm da chamada uv_getrusage que retorna uma uv_rusage_t struct.
- userCPUTime <integer> mapeia para ru_utime computado em microssegundos. É o mesmo valor que process.cpuUsage().user.
- systemCPUTime <integer> mapeia para ru_stime computado em microssegundos. É o mesmo valor que process.cpuUsage().system.
- maxRSS <integer> mapeia para ru_maxrss que é o tamanho máximo do conjunto residente usado em kilobytes.
- sharedMemorySize <integer> mapeia para ru_ixrss, mas não é suportado por nenhuma plataforma.
- unsharedDataSize <integer> mapeia para ru_idrss, mas não é suportado por nenhuma plataforma.
- unsharedStackSize <integer> mapeia para ru_isrss, mas não é suportado por nenhuma plataforma.
- minorPageFault <integer> mapeia para ru_minflt que é o número de page faults menores para o processo, veja este artigo para mais detalhes.
- majorPageFault <integer> mapeia para ru_majflt que é o número de page faults maiores para o processo, veja este artigo para mais detalhes. Este campo não é suportado no Windows.
- swappedOut <integer> mapeia para ru_nswap, mas não é suportado por nenhuma plataforma.
- fsRead <integer> mapeia para ru_inblock que é o número de vezes que o sistema de arquivos teve que executar a entrada.
- fsWrite <integer> mapeia para ru_oublock que é o número de vezes que o sistema de arquivos teve que executar a saída.
- ipcSent <integer> mapeia para ru_msgsnd, mas não é suportado por nenhuma plataforma.
- ipcReceived <integer> mapeia para ru_msgrcv, mas não é suportado por nenhuma plataforma.
- signalsCount <integer> mapeia para ru_nsignals, mas não é suportado por nenhuma plataforma.
- voluntaryContextSwitches <integer> mapeia para ru_nvcsw que é o número de vezes que uma troca de contexto da CPU resultou devido a um processo voluntariamente abandonar o processador antes que sua fatia de tempo fosse concluída (geralmente para aguardar a disponibilidade de um recurso). Este campo não é suportado no Windows.
- involuntaryContextSwitches <integer> mapeia para ru_nivcsw que é o número de vezes que uma troca de contexto da CPU resultou devido a um processo de prioridade mais alta se tornar executável ou porque o processo atual excedeu sua fatia de tempo. Este campo não é suportado no Windows.

ESMCJS

import { resourceUsage } from 'node:process';

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

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

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

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

Adicionado em: v0.5.9

message <Object>
sendHandle <net.Server> | <net.Socket>
options <Object> usado para parametrizar o envio de certos tipos de handles. options suporta as seguintes propriedades:
- keepOpen <boolean> Um valor que pode ser usado ao passar instâncias de net.Socket. Quando true, o socket é mantido aberto no processo de envio. Padrão: false.
callback <Function>
Retorna: <boolean>

Se o Node.js é iniciado com um canal IPC, o método process.send() pode ser usado para enviar mensagens ao processo pai. As mensagens serão recebidas como um evento 'message' no objeto ChildProcess do pai.

Se o Node.js não foi iniciado com um canal IPC, process.send será undefined.

A mensagem passa por serialização e análise. A mensagem resultante pode não ser a mesma que a originalmente enviada.

`process.setegid(id)`

Adicionado em: v2.0.0

id <string> | <number> Um nome ou ID de grupo

O método process.setegid() define a identidade de grupo efetiva do processo. (Veja setegid(2).) O id pode ser passado como um ID numérico ou um nome de grupo. Se um nome de grupo for especificado, este método bloqueia enquanto resolve o ID numérico associado.

ESMCJS

import process from 'node:process';

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

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

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

Esta função está disponível apenas em plataformas POSIX (ou seja, não Windows ou Android). Este recurso não está disponível em threads Worker.

`process.seteuid(id)`

Adicionado em: v2.0.0

id <string> | <number> Um nome de usuário ou ID

O método process.seteuid() define a identidade de usuário efetiva do processo. (Veja seteuid(2).) O id pode ser passado como um ID numérico ou uma string de nome de usuário. Se um nome de usuário for especificado, o método será bloqueado durante a resolução do ID numérico associado.

ESMCJS

import process from 'node:process';

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

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

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

Esta função está disponível apenas em plataformas POSIX (ou seja, não Windows ou Android). Este recurso não está disponível em threads Worker.

`process.setgid(id)`

Adicionado em: v0.1.31

id <string> | <number> O nome ou ID do grupo

O método process.setgid() define a identidade de grupo do processo. (Veja setgid(2).) O id pode ser passado como um ID numérico ou uma string de nome de grupo. Se um nome de grupo for especificado, este método será bloqueado durante a resolução do ID numérico associado.

ESMCJS

import process from 'node:process';

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

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

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

Esta função está disponível apenas em plataformas POSIX (ou seja, não Windows ou Android). Este recurso não está disponível em threads Worker.

`process.setgroups(groups)`

Adicionado em: v0.9.4

groups <integer[]>

O método process.setgroups() define os IDs de grupo suplementares para o processo Node.js. Esta é uma operação privilegiada que requer que o processo Node.js tenha root ou a capacidade CAP_SETGID.

O array groups pode conter IDs de grupo numéricos, nomes de grupo ou ambos.

ESMCJS

import process from 'node:process';

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

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

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

Esta função está disponível apenas em plataformas POSIX (ou seja, não Windows ou Android). Este recurso não está disponível em threads Worker.

`process.setuid(id)`

Adicionado em: v0.1.28

id <integer> | <string>

O método process.setuid(id) define a identidade do usuário do processo. (Veja setuid(2).) O id pode ser passado como um ID numérico ou uma string de nome de usuário. Se um nome de usuário for especificado, o método será bloqueado enquanto resolve o ID numérico associado.

ESMCJS

import process from 'node:process';

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

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

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

Esta função está disponível apenas em plataformas POSIX (ou seja, não Windows ou Android). Este recurso não está disponível em threads Worker.

`process.setSourceMapsEnabled(val)`

Adicionado em: v16.6.0, v14.18.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

val <boolean>

Esta função ativa ou desativa o suporte para Source Map v3 para rastreamentos de pilha.

Ela fornece os mesmos recursos que iniciar o processo do Node.js com as opções de linha de comando --enable-source-maps.

Apenas os source maps em arquivos JavaScript que são carregados após a ativação dos source maps serão analisados e carregados.

`process.setUncaughtExceptionCaptureCallback(fn)`

Adicionado em: v9.3.0

fn <Function> | <null>

A função process.setUncaughtExceptionCaptureCallback() define uma função que será invocada quando ocorrer uma exceção não capturada, que receberá o próprio valor da exceção como seu primeiro argumento.

Se tal função for definida, o evento 'uncaughtException' não será emitido. Se --abort-on-uncaught-exception foi passado da linha de comando ou definido através de v8.setFlagsFromString(), o processo não será abortado. Ações configuradas para ocorrer em exceções, como gerações de relatórios, também serão afetadas.

Para cancelar a definição da função de captura, process.setUncaughtExceptionCaptureCallback(null) pode ser usado. Chamar este método com um argumento não-null enquanto outra função de captura está definida lançará um erro.

Usar esta função é mutuamente exclusivo com o uso do módulo embutido domain obsoleto.

`process.sourceMapsEnabled`

Adicionado em: v20.7.0, v18.19.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

<boolean>

A propriedade process.sourceMapsEnabled retorna se o suporte para Source Map v3 para rastreamentos de pilha está ativado.

`process.stderr`

<Stream>

A propriedade process.stderr retorna um fluxo conectado a stderr (fd 2). É um net.Socket (que é um fluxo Duplex) a menos que fd 2 se refira a um arquivo, caso em que é um fluxo Writable.

process.stderr difere de outros fluxos Node.js de maneiras importantes. Consulte nota sobre E/S de processo para obter mais informações.

`process.stderr.fd`

<number>

Essa propriedade se refere ao valor do descritor de arquivo subjacente de process.stderr. O valor é fixo em 2. Nas threads Worker, este campo não existe.

`process.stdin`

<Stream>

A propriedade process.stdin retorna um fluxo conectado a stdin (fd 0). É um net.Socket (que é um fluxo Duplex) a menos que fd 0 se refira a um arquivo, caso em que é um fluxo Readable.

Para detalhes de como ler de stdin, consulte readable.read().

Como um fluxo Duplex, process.stdin também pode ser usado no modo "antigo" que é compatível com scripts escritos para Node.js antes da v0.10. Para obter mais informações, consulte Compatibilidade de fluxo.

No modo de fluxos "antigo", o fluxo stdin é pausado por padrão, então é preciso chamar process.stdin.resume() para ler dele. Observe também que chamar process.stdin.resume() em si mudaria o fluxo para o modo "antigo".

`process.stdin.fd`

<number>

Essa propriedade se refere ao valor do descritor de arquivo subjacente de process.stdin. O valor é fixo em 0. Nas threads Worker, este campo não existe.

`process.stdout`

<Stream>

A propriedade process.stdout retorna um fluxo conectado ao stdout (fd 1). É um net.Socket (que é um fluxo Duplex), a menos que fd 1 se refira a um arquivo, caso em que é um fluxo Writable.

Por exemplo, para copiar process.stdin para process.stdout:

ESMCJS

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

stdin.pipe(stdout);

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

stdin.pipe(stdout);

process.stdout difere de outros fluxos do Node.js de maneiras importantes. Consulte a nota sobre E/S de processo para obter mais informações.

`process.stdout.fd`

<number>

Esta propriedade se refere ao valor do descritor de arquivo subjacente de process.stdout. O valor é fixo em 1. Em threads Worker, este campo não existe.

Uma nota sobre E/S de processo

process.stdout e process.stderr diferem de outros fluxos do Node.js de maneiras importantes:

Esses comportamentos são em parte por razões históricas, pois alterá-los criaria incompatibilidade com versões anteriores, mas também são esperados por alguns usuários.

Gravações síncronas evitam problemas como saída escrita com console.log() ou console.error() sendo inesperadamente intercalada, ou não escrita se process.exit() for chamado antes que uma gravação assíncrona seja concluída. Consulte process.exit() para obter mais informações.

Aviso: Gravações síncronas bloqueiam o loop de eventos até que a gravação seja concluída. Isso pode ser quase instantâneo no caso de saída para um arquivo, mas sob alta carga do sistema, pipes que não estão sendo lidos na extremidade receptora, ou com terminais ou sistemas de arquivos lentos, é possível que o loop de eventos seja bloqueado com frequência e por tempo suficiente para ter impactos negativos graves no desempenho. Isso pode não ser um problema ao gravar em uma sessão de terminal interativa, mas considere isso particularmente cuidadoso ao fazer o registro de produção nos fluxos de saída do processo.

Para verificar se um fluxo está conectado a um contexto TTY, verifique a propriedade isTTY.

Por exemplo:

bash

$ 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

Consulte a documentação TTY para obter mais informações.

`process.throwDeprecation`

Adicionado em: v0.9.12

<boolean>

O valor inicial de process.throwDeprecation indica se o sinalizador --throw-deprecation está definido no processo Node.js atual. process.throwDeprecation é mutável, então se os avisos de depreciação resultam ou não em erros pode ser alterado em tempo de execução. Veja a documentação para o 'warning' event e o emitWarning() method para mais informações.

bash

$ 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`

Adicionado em: v0.1.104

<string>

A propriedade process.title retorna o título do processo atual (ou seja, retorna o valor atual de ps). Atribuir um novo valor a process.title modifica o valor atual de ps.

Quando um novo valor é atribuído, diferentes plataformas irão impor diferentes restrições de comprimento máximo no título. Normalmente, essas restrições são bastante limitadas. Por exemplo, no Linux e macOS, process.title é limitado ao tamanho do nome binário mais o comprimento dos argumentos da linha de comando porque definir o process.title sobrescreve a memória argv do processo. O Node.js v0.8 permitia strings de título de processo mais longas, também sobrescrevendo a memória environ, mas isso era potencialmente inseguro e confuso em alguns casos (bastante obscuros).

Atribuir um valor a process.title pode não resultar em um rótulo preciso em aplicativos de gerenciamento de processos, como o Monitor de Atividade do macOS ou o Gerenciador de Serviços do Windows.

`process.traceDeprecation`

Adicionado em: v0.8.0

<boolean>

A propriedade process.traceDeprecation indica se a flag --trace-deprecation está definida no processo Node.js atual. Consulte a documentação do evento 'warning' event e o método emitWarning() method para obter mais informações sobre o comportamento desta flag.

`process.umask()`

[Histórico]

Versão	Mudanças
v14.0.0, v12.19.0	Chamar `process.umask()` sem argumentos está obsoleto.
v0.1.19	Adicionado em: v0.1.19

[Estável: 0 - Obsoleto]

Estável: 0 Estabilidade: 0 - Obsoleto. Chamar process.umask() sem argumento faz com que o umask de todo o processo seja escrito duas vezes. Isso introduz uma condição de corrida entre as threads e é uma potencial vulnerabilidade de segurança. Não existe uma API alternativa segura e multiplataforma.

process.umask() retorna a máscara de criação de modo de arquivo do processo Node.js. Os processos filhos herdam a máscara do processo pai.

`process.umask(mask)`

Adicionado em: v0.1.19

mask <string> | <integer>

process.umask(mask) define a máscara de criação de modo de arquivo do processo Node.js. Os processos filhos herdam a máscara do processo pai. Retorna a máscara anterior.

ESMCJS

import { umask } from 'node:process';

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

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

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

Em threads Worker, process.umask(mask) lançará uma exceção.

`process.uptime()`

Adicionado em: v0.5.0

Retorna: <number>

O método process.uptime() retorna o número de segundos que o processo Node.js atual está em execução.

O valor de retorno inclui frações de segundo. Use Math.floor() para obter segundos inteiros.

`process.version`

Adicionado em: v0.1.3

<string>

A propriedade process.version contém a string de versão do Node.js.

ESMCJS

import { version } from 'node:process';

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

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

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

Para obter a string de versão sem o v prefixado, use process.versions.node.

`process.versions`

[Histórico]

Versão	Mudanças
v9.0.0	A propriedade `v8` agora inclui um sufixo específico do Node.js.
v4.2.0	A propriedade `icu` agora é suportada.
v0.2.0	Adicionado em: v0.2.0

<Object>

A propriedade process.versions retorna um objeto listando as strings de versão do Node.js e suas dependências. process.versions.modules indica a versão ABI atual, que é incrementada sempre que uma API C++ muda. O Node.js se recusará a carregar módulos que foram compilados em uma versão ABI de módulo diferente.

ESMCJS

import { versions } from 'node:process';

console.log(versions);

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

console.log(versions);

Gerará um objeto similar a:

bash

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

Códigos de Saída

O Node.js normalmente sairá com um código de status 0 quando não houver mais operações assíncronas pendentes. Os seguintes códigos de status são usados em outros casos:

1 Exceção Fatal Não Capturada: Ocorreu uma exceção não capturada e não foi tratada por um domínio ou um manipulador de evento 'uncaughtException'.
2: Não utilizado (reservado pelo Bash para uso indevido interno)
3 Erro de Análise JavaScript Interno: O código-fonte JavaScript interno no processo de inicialização do Node.js causou um erro de análise. Isso é extremamente raro e geralmente só pode acontecer durante o desenvolvimento do próprio Node.js.
4 Falha de Avaliação JavaScript Interna: O código-fonte JavaScript interno no processo de inicialização do Node.js não conseguiu retornar um valor de função quando avaliado. Isso é extremamente raro e geralmente só pode acontecer durante o desenvolvimento do próprio Node.js.
5 Erro Fatal: Ocorreu um erro fatal irrecuperável no V8. Normalmente, uma mensagem será impressa em stderr com o prefixo FATAL ERROR.
6 Manipulador de Exceção Interna Não-Função: Ocorreu uma exceção não capturada, mas a função interna do manipulador de exceção fatal foi definida de alguma forma como não-função e não pôde ser chamada.
7 Falha de Tempo de Execução do Manipulador de Exceção Interna: Ocorreu uma exceção não capturada e a própria função interna do manipulador de exceção fatal lançou um erro ao tentar tratá-la. Isso pode acontecer, por exemplo, se um manipulador 'uncaughtException' ou domain.on('error') lançar um erro.
8: Não utilizado. Em versões anteriores do Node.js, o código de saída 8 às vezes indicava uma exceção não capturada.
9 Argumento Inválido: Uma opção desconhecida foi especificada ou uma opção que exige um valor foi fornecida sem um valor.
10 Falha de Tempo de Execução JavaScript Interna: O código-fonte JavaScript interno no processo de inicialização do Node.js lançou um erro quando a função de inicialização foi chamada. Isso é extremamente raro e geralmente só pode acontecer durante o desenvolvimento do próprio Node.js.
12 Argumento de Depuração Inválido: As opções --inspect e/ou --inspect-brk foram definidas, mas o número da porta escolhido era inválido ou não estava disponível.
13 Await de Nível Superior Não Resolvido: await foi usado fora de uma função no código de nível superior, mas a Promise passada nunca foi resolvida.
14 Falha de Snapshot: O Node.js foi iniciado para construir um snapshot de inicialização V8 e falhou porque certos requisitos do estado da aplicação não foram atendidos.
\>128 Saídas de Sinal: Se o Node.js receber um sinal fatal como SIGKILL ou SIGHUP, seu código de saída será 128 mais o valor do código do sinal. Esta é uma prática POSIX padrão, uma vez que os códigos de saída são definidos para serem inteiros de 7 bits, e as saídas de sinal definem o bit de ordem superior e, em seguida, contêm o valor do código do sinal. Por exemplo, o sinal SIGABRT tem valor 6, então o código de saída esperado será 128 + 6, ou 134.

Processo ​

Eventos do Processo ​

Evento: 'beforeExit' ​

Evento: 'disconnect' ​

Evento: 'exit' ​

Evento: 'message' ​

Evento: 'multipleResolves' ​

Evento: 'rejectionHandled' ​

Evento: 'workerMessage' ​

Evento: 'uncaughtException' ​

Aviso: Usando 'uncaughtException' corretamente ​

Evento: 'uncaughtExceptionMonitor' ​

Evento: 'unhandledRejection' ​

Evento: 'warning' ​

Emitindo avisos personalizados ​

Nomes de avisos do Node.js ​

Evento: 'worker' ​

Eventos de Sinal ​

process.abort() ​

process.allowedNodeEnvironmentFlags ​

process.arch ​

process.argv ​

process.argv0 ​

process.channel ​

process.channel.ref() ​

process.channel.unref() ​

process.chdir(directory) ​

process.config ​

process.connected ​

process.constrainedMemory() ​

process.availableMemory() ​

process.cpuUsage([previousValue]) ​

process.cwd() ​

process.debugPort ​

process.disconnect() ​

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

process.emitWarning(warning[, options]) ​

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

Evitando avisos duplicados ​

process.env ​

process.execArgv ​

process.execPath ​

process.exit([code]) ​

process.exitCode ​

process.features.cached_builtins ​

process.features.debug ​

process.features.inspector ​

process.features.ipv6 ​

process.features.require_module ​

process.features.tls ​

process.features.tls_alpn ​

process.features.tls_ocsp ​

process.features.tls_sni ​

process.features.typescript ​

process.features.uv ​

process.finalization.register(ref, callback) ​

process.finalization.registerBeforeExit(ref, callback) ​

process.finalization.unregister(ref) ​

process.getActiveResourcesInfo() ​

process.getBuiltinModule(id) ​

process.getegid() ​

process.geteuid() ​

process.getgid() ​

process.getgroups() ​

process.getuid() ​

process.hasUncaughtExceptionCaptureCallback() ​

process.hrtime([time]) ​

process.hrtime.bigint() ​

process.initgroups(user, extraGroup) ​

process.kill(pid[, signal]) ​

process.loadEnvFile(path) ​

process.mainModule ​

process.memoryUsage() ​

process.memoryUsage.rss() ​

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

Quando usar queueMicrotask() vs. process.nextTick() ​

process.noDeprecation ​

process.permission ​

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

process.pid ​

Processo

Eventos do Processo

Evento: `'beforeExit'`

Evento: `'disconnect'`

Evento: `'exit'`

Evento: `'message'`

Evento: `'multipleResolves'`

Evento: `'rejectionHandled'`

Evento: `'workerMessage'`

Evento: `'uncaughtException'`

Aviso: Usando `'uncaughtException'` corretamente

Evento: `'uncaughtExceptionMonitor'`

Evento: `'unhandledRejection'`

Evento: `'warning'`

Emitindo avisos personalizados

Nomes de avisos do Node.js

Evento: `'worker'`

Eventos de Sinal

`process.abort()`

`process.allowedNodeEnvironmentFlags`

`process.arch`

`process.argv`

`process.argv0`

`process.channel`

`process.channel.ref()`

`process.channel.unref()`

`process.chdir(directory)`

`process.config`

`process.connected`

`process.constrainedMemory()`

`process.availableMemory()`

`process.cpuUsage([previousValue])`

`process.cwd()`

`process.debugPort`

`process.disconnect()`

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

`process.emitWarning(warning[, options])`

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

Evitando avisos duplicados

`process.env`

`process.execArgv`

`process.execPath`

`process.exit([code])`

`process.exitCode`

`process.features.cached_builtins`

`process.features.debug`

`process.features.inspector`

`process.features.ipv6`

`process.features.require_module`

`process.features.tls`

`process.features.tls_alpn`

`process.features.tls_ocsp`

`process.features.tls_sni`

`process.features.typescript`

`process.features.uv`

`process.finalization.register(ref, callback)`

`process.finalization.registerBeforeExit(ref, callback)`

`process.finalization.unregister(ref)`

`process.getActiveResourcesInfo()`

`process.getBuiltinModule(id)`

`process.getegid()`

`process.geteuid()`

`process.getgid()`

`process.getgroups()`

`process.getuid()`

`process.hasUncaughtExceptionCaptureCallback()`

`process.hrtime([time])`

`process.hrtime.bigint()`

`process.initgroups(user, extraGroup)`

`process.kill(pid[, signal])`

`process.loadEnvFile(path)`

`process.mainModule`

`process.memoryUsage()`

`process.memoryUsage.rss()`

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

Quando usar `queueMicrotask()` vs. `process.nextTick()`

`process.noDeprecation`

`process.permission`

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

`process.pid`