Skip to content

Node.js Folha de referência

Runtime JavaScript construído sobre o motor V8 do Chrome para desenvolvimento no lado do servidor.

01

Primeiros Passos

REPL e Execução de Scripts

O REPL (Read-Eval-Print Loop) é um shell interativo para experimentar código Node.js. Use node --watch para reinício automático no desenvolvimento. ES modules exigem type:module no package.json ou a extensão .mjs.

nodejs
# start the REPL (interactive shell)
node

# run a script
node app.js

# run with ES modules (type: module in package.json)
node --input-type=module app.js

# execute inline code
node -e "console.log(process.version)"

# watch mode (auto-restart on change)
node --watch app.js

Versão e Flags de Runtime

node --version imprime a versão do runtime. --trace-warnings mostra stack traces para avisos de runtime. NODE_OPTIONS é uma única variável de ambiente que guarda flags da CLI, útil dentro de contêineres ou scripts npm. --inspect abre o depurador do Chrome DevTools.

nodejs
# check version
node --version    # v20.11.0
node -p "process.versions.v8"

# enable warning stack traces
node --trace-warnings app.js

# pass NODE_OPTIONS (max ~128KB string)
NODE_OPTIONS="--max-old-space-size=4096" node app.js

# inspect memory usage at runtime
node --inspect app.js

package.json e Init do Projeto

npm init cria o package.json. O campo "type" decide o sistema de módulos padrão: "module" habilita sintaxe ES module nos arquivos .js, "commonjs" (padrão) mantém require/module.exports. "main" é o ponto de entrada quando o pacote é requerido.

nodejs
# scaffold a project (answer prompts)
npm init

# non-interactive defaults
npm init -y

# "type" controls module system
# "commonjs" (default) -> require/module.exports
# "module"              -> import/export
{
  "name": "my-app",
  "version": "1.0.0",
  "type": "module",
  "main": "index.js",
  "scripts": { "start": "node index.js" }
}

CommonJS vs ES Modules

Node suporta dois sistemas de módulos. CommonJS (require/module.exports) é síncrono e o padrão histórico. ES Modules (import/export) são o padrão moderno. A extensão do arquivo (.mjs/.cjs) ou o campo "type" do package.json decide qual parser é usado nos arquivos .js.

nodejs
# CommonJS (.cjs or type:commonjs) ----
const fs = require('fs');                 // import
module.exports = { greet: () => 'hi' };   // export

# ES Modules (.mjs or type:module) -------
import fs from 'fs';                      // import
export function greet() { return 'hi'; }  // named export
export default { greet };                 // default export

# .mjs is always ESM, .cjs is always CJS
node file.mjs   # forced ESM
node file.cjs   # forced CJS

Objetos Globais

Node fornece globais como process, console, Buffer e timers sem imports. __dirname e __filename são exclusivos do CommonJS — em ES Modules use import.meta.url no lugar. global é o objeto de escopo raiz (como window nos navegadores).

nodejs
# available everywhere, no import needed
global;        // global namespace object
process;       // env, argv, stdin/stdout
console;       // log, error, warn, table
setTimeout;    // schedule a callback
setInterval;   // schedule repeating callback
Buffer;        // binary data (Uint8Array)
queueMicrotask;// schedule microtask
structuredClone; // deep clone

# CommonJS-only globals (not in ESM)
__dirname;     // current directory
__filename;    // current file path

Scripts Executáveis (Shebang)

Uma linha shebang (#!/usr/bin/env node) permite que um arquivo rode como comando autônomo no Unix. Depois de chmod +x, execute ./cli.js diretamente. O campo "bin" do package.json mapeia um nome de comando a um script, usado por ferramentas CLI publicadas no npm para que a instalação global exponha o comando.

nodejs
#!/usr/bin/env node
// cli.js - make a file directly runnable
const name = process.argv[2] || 'world';
console.log(`Hello, ${name}!`);

# make it executable (Unix) and run directly
chmod +x cli.js
./cli.js Alice        # Hello, Alice!

# or wire it up in package.json
{
  "bin": { "mycli": "./cli.js" }
}
02

Sistema de Módulos

CommonJS require e exports

require() carrega sincronamente um módulo CommonJS e retorna seu module.exports. require resolve caminhos relativos (./, ../), embutidos (fs) e node_modules. Sempre atribua a module.exports (não a exports) ao substituir a exportação inteira, porque exports é só um apelido para module.exports inicialmente.

nodejs
// math.js
function add(a, b) { return a + b; }
const PI = 3.14;

// export via module.exports
module.exports = { add, PI };
// or: exports.add = add; exports.PI = PI;

// app.js
const math = require('./math');      // .js optional
console.log(math.add(1, 2));          // 3
console.log(math.PI);                 // 3.14

// destructuring
const { add } = require('./math');
console.log(add(5, 7));               // 12

ES Modules import/export

ES Modules usam import/export estático — as ligações são vivas e içadas. A exportação default é importada com qualquer nome (sem chaves); exportações nomeadas exigem chaves com nomes correspondentes. import * as cria um objeto de namespace. ESM é assíncrono por design e o padrão moderno.

nodejs
// math.mjs (or type:module)
export function add(a, b) { return a + b; }
export const PI = 3.14;
export default function square(x) { return x * x; }

// app.mjs
import square, { add, PI } from './math.mjs';
console.log(add(1, 2));     // 3
console.log(square(5));     // 25

// import all as namespace
import * as math from './math.mjs';
console.log(math.PI);       // 3.14

import() Dinâmico

import() é um import dinâmico e assíncrono, utilizável tanto em CJS quanto em ESM. Retorna uma Promise que resolve para o namespace do módulo, habilitando lazy-loading e imports condicionais — ótimo para reduzir o tempo de inicialização ou carregar recursos opcionais. Use-o para code-splitting em servidores também.

nodejs
// dynamic import returns a Promise
async function loadPlugin(name) {
  const mod = await import(`./plugins/${name}.mjs`);
  return mod.default;
}

// lazy-load heavy modules on demand
if (needPdf) {
  const { exportPdf } = await import('./pdf.mjs');
  exportPdf(data);
}

// works in both CommonJS and ESM
import('./optional.mjs')
  .then(mod => mod.run())
  .catch(err => console.error('load failed', err));

Módulos Embutidos

Node traz dezenas de módulos embutidos — sem npm install. A maioria expõe APIs de callback; muitos também oferecem variantes de promise no caminho 'módulo/promises' (fs/promises, dns/promises, stream/promises). require('módulo') (sem ./) resolve primeiro os embutidos, depois node_modules.

nodejs
// core modules - no install, just require/import
const fs = require('fs');            // file system
const path = require('path');        // path handling
const http = require('http');        // HTTP server/client
const os = require('os');            // OS info
const crypto = require('crypto');    // hashing/encryption
const { EventEmitter } = require('events');
const { Buffer } = require('buffer');
const stream = require('stream');    // streams
const net = require('net');          // TCP
const child_process = require('child_process');

// some are promise-based (Node 10+)
const fsp = require('fs/promises');  // async/await fs

Cache de Módulos e Dependências Circulares

require() cacheia módulos pelo caminho resolvido, então o mesmo código de módulo roda uma vez e as exportações são reutilizadas. Dependências circulares funcionam, mas o módulo carregado primeiro vê um objeto de exportações incompleto (parcial) do segundo — projete em torno delas. delete require.cache para hot-reload durante o desenvolvimento.

nodejs
// modules are cached after first load
// a.js
require('./b');                 // b loads, sets module.exports
const b = require('./b');       // returns cached b (same object)
console.log(b === require('./b')); // true

// circular dependency: a -> b -> a
// a.js: const b = require('./b'); b.f();
// b.js: const a = require('./a'); // a is PARTIAL here!
//       module.exports = { f: () => a.x };

// inspect the cache
console.log(require.cache);     // map of loaded modules
delete require.cache[require.resolve('./b')]; // force reload

__dirname e import.meta.url

__dirname e __filename são globais exclusivos do CommonJS que dão o caminho atual de pasta/arquivo. ES Modules não têm essas globais — derive-as de import.meta.url via fileURLToPath. import.meta.url é a URL file:// do módulo atual e o substituto ESM de __filename.

nodejs
// CommonJS - synchronous path globals
console.log(__dirname);   // /app/src
console.log(__filename);  // /app/src/index.js

// ES Modules - no __dirname, use import.meta
import { fileURLToPath } from 'url';
import { dirname, join } from 'path';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
const dataPath = join(__dirname, 'data.json');

// import.meta also carries the module URL
console.log(import.meta.url);  // file:///app/src/index.mjs
03

npm e pnpm

npm init e package.json

npm init cria o esqueleto do package.json. -y pula as perguntas com padrões. npm set guarda configuração em ~/.npmrc para inits futuros. Pacotes com escopo (@org/nome) são úteis para organizações e para evitar colisões de nomes no registro.

nodejs
# create package.json interactively
npm init

# accept all defaults
npm init -y

# pnpm equivalent
pnpm init

# set author/license globally
npm set init-author-name "Alice"
npm set init-license MIT

# scope packages with @username
npm init --scope=@myorg

Instalando Dependências

npm install (sem argumentos) instala todas as dependências listadas. Com um nome, adiciona ao package.json. --save-dev o coloca em devDependencies (ferramentas de teste/build, não distribuídas). ^ permite atualizações de minor+patch, ~ permite só patch. -g instala ferramentas CLI globalmente.

nodejs
# install everything in package.json
npm install            # alias: npm i
pnpm install           # alias: pnpm i

# add a runtime dependency -> dependencies
npm install express
pnpm add express

# add a dev-only dependency -> devDependencies
npm install --save-dev jest     # npm i -D jest
pnpm add -D jest

# install a specific version
npm install [email protected]
npm install lodash@^4.17.0      # caret: 4.x
npm install lodash@~4.17.0      # tilde: 4.17.x

# global install (CLI tools)
npm install -g pm2
pnpm add -g pm2

Scripts npm

Scripts no package.json rodam via npm run <nome>. start e test são especiais (npm start / npm test). Hooks pre/post (pretest, postbuild) rodam automaticamente. Use -- para repassar argumentos ao comando subjacente. O pnpm deixa você pular a palavra "run" para scripts personalizados.

nodejs
// package.json
{
  "scripts": {
    "start": "node index.js",
    "dev": "node --watch index.js",
    "test": "jest",
    "build": "tsc && vite build"
  }
}

# run a script
npm run dev          # npm run-script dev
pnpm dev             # pnpm has no "run" requirement

# "start" and "test" have shortcuts
npm start
npm test

# pre/post hooks run automatically
// "pretest": "npm run lint",
// "postbuild": "npm run deploy"

# pass extra args with --
npm run build -- --mode production

npx e pnpm dlx

npx roda o binário de um pacote sem instalação global — baixa, executa e descarta. Perfeito para scaffolders (create-vite) e para rodar ferramentas locais de node_modules/.bin. --yes pula a confirmação de instalação. pnpm dlx é a contraparte no pnpm.

nodejs
# run a one-off command without installing globally
npx create-vite my-app
npx cowsay "hello"

# pin a version
npx prettier@3 --write .

# pnpm equivalent
pnpm dlx create-vite my-app

# execute a local bin from node_modules
npx jest            # runs ./node_modules/.bin/jest

# never prompt, always download latest
npx --yes create-react-app my-app

Versionamento e Lockfiles

SemVer: MAJOR para mudanças quebradoras, MINOR para recursos, PATCH para correções. ^ (circunflexo) é o padrão do npm e permite atualizações de minor+patch; ~ (til) apenas patch. Lockfiles (package-lock.json) congelam a árvore completa de dependências para instalações reproduzíveis — use npm ci no CI por velocidade e segurança.

nodejs
# semantic versioning: MAJOR.MINOR.PATCH
# 1.4.2 -> 1:breaking 4:feature 2:fix
"^1.4.2"  # >=1.4.2 <2.0.0  (caret, default)
"~1.4.2"  # >=1.4.2 <1.5.0  (tilde)
"1.4.2"   # exact 1.4.2
">=1.4.0 <2.0.0" # range

# lockfiles pin the installed tree
npm install       # writes/updates package-lock.json
pnpm install      # writes pnpm-lock.yaml
yarn install      # writes yarn.lock

# install exactly as locked (CI)
npm ci            # clean install from lockfile

# find outdated deps
npm outdated
npm update        # update within ^ ranges

Publicação e Ciclo de Vida

npm publish envia seu pacote ao registro. npm version incrementa a versão, cria uma tag git e comita. Hooks de ciclo de vida (prepublishOnly, postpublish) automatizam build/teste no release. Unpublish só é permitido dentro de 72 horas — prefira npm deprecate para versões antigas.

nodejs
# login once
npm login

# publish to the registry
npm publish
npm publish --access public   # scoped default restricted

# bump version (updates package.json + tag + commit)
npm version patch   # 1.0.0 -> 1.0.1
npm version minor   # 1.0.0 -> 1.1.0
npm version major   # 1.0.0 -> 2.0.0

# lifecycle scripts (in package.json)
// "prepublishOnly": "npm test && npm run build",
// "prepublish": "npm run build",
// "postpublish": "git push --tags"

# unpublish within 72h
npm unpublish [email protected]
04

Sistema de Arquivos (fs)

Lendo Arquivos

fs oferece APIs síncrona (readFileSync), de callback (readFile) e de promise (readFile de fs/promises). Chamadas síncronas bloqueiam o event loop — evite em servidores. fs/promises é a escolha moderna para async/await. Sem uma codificação, readFile retorna um Buffer.

nodejs
const fs = require('fs');

// synchronous (blocks the event loop)
const text = fs.readFileSync('data.txt', 'utf8');
const buf = fs.readFileSync('image.png');  // Buffer

// asynchronous with callback (error-first)
fs.readFile('data.txt', 'utf8', (err, data) => {
  if (err) return console.error(err);
  console.log(data);
});

// async with fs/promises (preferred)
const fsp = require('fs/promises');
async function read() {
  const text = await fsp.readFile('data.txt', 'utf8');
  return text;
}

Escrevendo Arquivos

writeFile substitui o arquivo inteiro por padrão. A opção flag muda o comportamento: 'a' anexa, 'wx' falha (EEXIST) se o arquivo já existe — útil para criação atômica de arquivos. JSON deve ser stringificado antes de escrever. Escritas síncronas bloqueiam; prefira fs/promises.

nodejs
const fs = require('fs');
const fsp = require('fs/promises');

// sync
fs.writeFileSync('out.txt', 'hello');

// async callback
fs.writeFile('log.txt', 'line1\n', err => {
  if (err) throw err;
});

// promise
await fsp.writeFile('config.json', JSON.stringify(cfg, null, 2));

// flags: 'w' write (default), 'a' append, 'wx' fail if exists
await fsp.writeFile('new.txt', 'x', { flag: 'wx' }); // throws if exists

Diretórios

mkdir com { recursive: true } imita mkdir -p. readdir lista entradas; { withFileTypes: true } retorna objetos Dirent cujos isDirectory()/isFile() evitam chamadas stat extras. fsp.rm com recursive+force substitui rmdir para diretórios não vazios (Node 14+).

nodejs
const fsp = require('fs/promises');

// create (recursive like mkdir -p)
await fsp.mkdir('a/b/c', { recursive: true });

// list entries
const entries = await fsp.readdir('.');
// ['app.js', 'data', 'package.json']

// list with type info
const detailed = await fsp.readdir('.', { withFileTypes: true });
detailed.forEach(e => console.log(e.name, e.isDirectory()));

// remove
await fsp.rmdir('empty');             // empty dir only
await fsp.rm('folder', { recursive: true, force: true }); // rm -rf

// sync versions exist too: mkdirSync, readdirSync, rmSync

Stats e Metadados de Arquivos

stat() retorna um objeto Stats com size, mtime e helpers de tipo. Não use fs.exists (obsoleto); use access() num try/catch para checagens de existência sem corrida — embora abrir o arquivo diretamente seja mais seguro. fsWatch emite eventos de mudança, mas pode ser inconsistente entre plataformas.

nodejs
const fsp = require('fs/promises');

const stats = await fsp.stat('data.txt');
stats.isFile();          // true
stats.isDirectory();     // false
stats.size;              // bytes
stats.mtime;             // Date modified
stats.birthtime;         // Date created
stats.mode;              // permission bits

// check existence (avoid existsSync for races)
try {
  await fsp.access('config.json');
  console.log('exists');
} catch {
  console.log('missing');
}

// watch for changes
const watcher = fs.watch('.');
watcher.on('change', (eventType, filename) => {});

API fs.promises

fs/promises (Node 10+) fornece versões baseadas em promise das funções de fs, ideal para async/await. opendir() retorna um iterator assíncrono para travessia de diretórios eficiente em memória. Combine com path.join para caminhos portáteis. Todas as funções lançam erro — envolva em try/catch.

nodejs
const fsp = require('fs/promises');
const path = require('path');

// full async/await file operations
async function loadConfig() {
  const file = path.join(__dirname, 'config.json');
  const raw = await fsp.readFile(file, 'utf8');
  return JSON.parse(raw);
}

async function saveConfig(cfg) {
  const file = path.join(__dirname, 'config.json');
  await fsp.writeFile(file, JSON.stringify(cfg, null, 2));
}

// iterate directory tree
for await (const entry of await fsp.opendir('.')) {
  console.log(entry.name);
}

Append, Rename, Delete

appendFile adiciona conteúdo ao fim (cria o arquivo se ausente). rename é atômico no mesmo sistema de arquivos e usado para mover arquivos. unlink deleta um arquivo. copyFile copia conteúdo; fsp.cp (Node 16+) trata diretórios recursivamente. truncate redimensiona um arquivo para o comprimento dado.

nodejs
const fsp = require('fs/promises');

// append to a file (creates if missing)
await fsp.appendFile('log.txt', new Date() + ' started\n');

// atomic rename (also for moving)
await fsp.rename('old.txt', 'new.txt');
// move across dirs
await fsp.rename('a/x.txt', 'b/x.txt');

// delete a file
await fsp.unlink('temp.txt');

// copy
await fsp.copyFile('src.txt', 'dest.txt');
// or fsp.cp('src', 'dest', { recursive: true })

// truncate to a length
await fsp.truncate('data.bin', 1024);
05

Manipulação de Caminhos

path.join e path.resolve

path.join concatena segmentos usando o separador da plataforma e normaliza o resultado. path.resolve produz um caminho absoluto partindo de process.cwd(); um segmento absoluto descarta os segmentos anteriores. Sempre use path.join em vez de concatenação de strings, para que os caminhos funcionem no Windows e no POSIX.

nodejs
const path = require('path');

// join segments with the OS separator
path.join('src', 'utils', 'file.js');
// 'src/utils/file.js' (Linux)  or 'src\utils\file.js' (Windows)

// resolve to an ABSOLUTE path (from cwd)
path.resolve('src', 'file.js');
// '/current/dir/src/file.js'

// resolve with absolute segment resets
path.resolve('/a', 'b', '/c', 'd');   // '/c/d'

// normalize '..' and '.' segments
path.normalize('a/b/../c/./d');        // 'a/c/d'

// never hardcode '/' — use path.join for portability

dirname, basename, extname

dirname retorna o diretório, basename o nome do arquivo (opcionalmente removendo uma extensão), e extname a última extensão (incluindo o ponto). Para extensões em várias partes como .tar.gz, só o .gz final é retornado. São operações puras de string — sem acesso ao sistema de arquivos.

nodejs
const path = require('path');
const file = '/app/src/utils/helper.js';

path.dirname(file);    // '/app/src/utils'
path.basename(file);   // 'helper.js'
path.basename(file, '.js'); // 'helper' (strip ext)
path.extname(file);    // '.js'
path.extname('archive.tar.gz'); // '.gz' (last ext)

// for the current file (CommonJS)
path.dirname(__filename);  // current dir
path.basename(__filename); // current file name

path.parse e format

path.parse divide um caminho em root, dir, base, name e ext. path.format os remonta. path.relative calcula o caminho relativo necessário para ir de um diretório a outro. Juntos, tornam a manipulação de caminhos declarativa, em vez de fatiamento de strings trabalhoso.

nodejs
const path = require('path');

// decompose a path into parts
const p = path.parse('/app/src/helper.test.js');
// { root: '/', dir: '/app/src',
//   base: 'helper.test.js', name: 'helper.test', ext: '.js' }

// rebuild from a parsed object
const rebuilt = path.format({
  dir: '/app/dist',
  name: 'bundle',
  ext: '.min.js'
});
// '/app/dist/bundle.min.js'

// get the relative path from A to B
path.relative('/a/b/c', '/a/x');   // '../../x'

Caminhos Multiplataforma

path.sep e path.delimiter diferem por SO. path.win32 e path.posix forçam um parser específico, independentemente do SO hospedeiro — prático ao processar caminhos de outra plataforma. Use path.delimiter para dividir variáveis de ambiente estilo PATH de forma portátil, em vez de fixar ':' ou ';'.

nodejs
const path = require('path');

// platform-specific values
path.sep;           // '/' (POSIX) or '\\' (Windows)
path.delimiter;     // ':' (POSIX) or ';' (Windows)

// force a specific platform's behavior
path.win32.join('a', 'b');   // 'a\\b'
path.posix.join('a', 'b');   // 'a/b'

// parse PATH env var portably
process.env.PATH.split(path.delimiter).forEach(dir => {
  console.log(dir);
});

// check if absolute
path.isAbsolute('/etc');     // true
path.isAbsolute('a/b');      // false
path.win32.isAbsolute('C:\\'); // true

URLs de Arquivo e pathToFileURL

ES Modules são identificados por URLs file://. Use url.pathToFileURL para transformar um caminho comum numa URL para import() dinâmico, e url.fileURLToPath para o caminho inverso. Em ESM, import.meta.url já é uma URL de arquivo — converta-a em caminho com fileURLToPath para replicar __filename.

nodejs
const path = require('path');
const url = require('url');

// convert a path to a file:// URL (ESM import)
const fileUrl = url.pathToFileURL('/app/src/mod.mjs');
// URL { href: 'file:///app/src/mod.mjs' }

// and back
const p = url.fileURLToPath('file:///app/src/mod.mjs');
// '/app/src/mod.mjs'

// in ESM, import.meta.url is already a file URL
// convert to a normal path:
import { fileURLToPath } from 'url';
const __filename = fileURLToPath(import.meta.url);
06

Servidor HTTP

Servidor HTTP Básico

http.createServer retorna um servidor; o callback trata cada requisição. res.writeHead define o código de status e os headers, res.end envia o corpo e finaliza a resposta. listen() começa a aceitar conexões na porta dada. Um processo Node atende muitas requisições concorrentes via event loop.

nodejs
const http = require('http');

const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('Hello, World!\n');
});

// listen on a port
server.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

// or with a host and backlog
server.listen(3000, '127.0.0.1', 511, () => {});

Request e Response

req expõe method, url e headers; res permite definir statusCode/headers e depois write+end. res.end PRECISA ser chamado para finalizar a resposta. Para payloads grandes, transmita os dados via res.write ou conecte um Readable a res com pipe, para não bufferizar tudo na memória.

nodejs
const http = require('http');

http.createServer((req, res) => {
  // request info
  console.log(req.method);   // 'GET'
  console.log(req.url);      // '/users?id=5'
  console.log(req.headers);  // { host, 'user-agent', ... }

  // response helpers
  res.statusCode = 200;
  res.setHeader('Content-Type', 'application/json');
  res.write('partial chunk\n');
  res.end(JSON.stringify({ ok: true }));
}).listen(3000);

// streaming a large response
res.writeHead(200);
readStream.pipe(res);   // pipe file -> response

Roteamento e Parsing de URL

Node não tem roteador embutido — implemente um com if/else sobre req.method e req.url, ou use o construtor URL para analisar pathname e searchParams. Para apps reais, recorra ao Express ou ao roteador de um framework. O construtor URL precisa de uma base ao analisar um req.url relativo.

nodejs
const http = require('http');
const { URL } = require('url');

http.createServer((req, res) => {
  const url = new URL(req.url, 'http://localhost');
  const path = url.pathname;
  const q = url.searchParams.get('id');

  if (req.method === 'GET' && path === '/') {
    res.end('home');
  } else if (path === '/users') {
    res.end('users');
  } else {
    res.writeHead(404);
    res.end('not found');
  }
}).listen(3000);

Tratando JSON e Corpo POST

Os corpos de requisição chegam como stream — você precisa coletar os chunks antes de analisar. O padrão de async iterator (for await de req) é a abordagem moderna. Sempre defina Content-Type: application/json ao responder com JSON. Em produção, limite o tamanho do corpo para prevenir exaustão de memória.

nodejs
const http = require('http');

http.createServer(async (req, res) => {
  if (req.method === 'POST') {
    // collect the streamed body
    const chunks = [];
    for await (const chunk of req) chunks.push(chunk);
    const body = JSON.parse(Buffer.concat(chunks).toString());

    res.writeHead(200, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify({ received: body }));
  }
}).listen(3000);

// test: curl -X POST localhost:3000 -d '{"a":1}'

Eventos e Erros do Servidor

O servidor é um EventEmitter. 'error' precisa ser tratado — EADDRINUSE significa que a porta está ocupada. 'connection' dispara por socket de cliente. Para desligamento gracioso, escute SIGTERM/SIGINT e chame server.close() para que requisições em andamento terminem antes do processo sair.

nodejs
const server = http.createServer(handler);

server.on('listening', () => console.log('ready'));
server.on('connection', socket => console.log('client connected'));
server.on('error', err => {
  if (err.code === 'EADDRINUSE') {
    console.error('port 3000 already in use');
  }
});
server.on('close', () => console.log('server closed'));

// graceful shutdown
process.on('SIGTERM', () => {
  server.close(() => process.exit(0));
});

server.listen(3000);

HTTPS e Cliente HTTP

https.createServer exige chave privada e certificado (ex.: do Let's Encrypt). Para requisições de saída, Node 18+ traz um fetch() global — prefira-o à API de callback bruta do http.get. fetch é baseado em promise e suporta async/await, headers e streams.

nodejs
// HTTPS server (needs TLS certs)
const https = require('https');
const fs = require('fs');

https.createServer({
  key: fs.readFileSync('key.pem'),
  cert: fs.readFileSync('cert.pem')
}, handler).listen(443);

// HTTP client: simple GET
http.get('http://example.com', res => {
  let data = '';
  res.on('data', c => data += c);
  res.on('end', () => console.log(data));
});

// modern fetch (Node 18+, global, promise-based)
const res = await fetch('https://api.example.com');
const json = await res.json();
07

Básico do Express

Setup do Express e Hello World

Express é o framework web Node mais popular. app.get registra um handler de rota; res.send envia uma resposta (detectando o Content-Type automaticamente). app.listen inicia o servidor. O Express embrulha o módulo http do Node com roteamento, middleware e helpers de conveniência.

nodejs
// install: npm install express
import express from 'express';

const app = express();
const PORT = 3000;

app.get('/', (req, res) => {
  res.send('Hello, World!');
});

app.listen(PORT, () => {
  console.log(`Server on http://localhost:${PORT}`);
});

Rotas e Parâmetros de Rota

O Express casa verbos HTTP (get/post/put/delete) com caminhos. :id captura segmentos de URL em req.params; req.query guarda valores da query string. app.route permite encadear múltiplos verbos para o mesmo caminho. As rotas casam na ordem de registro, então defina as rotas específicas antes das genéricas.

nodejs
app.get('/users', (req, res) => res.send('list users'));
app.post('/users', (req, res) => res.send('create user'));

// URL parameters
app.get('/users/:id', (req, res) => {
  res.send(`user ${req.params.id}`);
});

// query strings: /search?q=node
app.get('/search', (req, res) => {
  res.send(`searching: ${req.query.q}`);
});

// chain handlers for one path
app.route('/book')
  .get((req, res) => res.send('get book'))
  .post((req, res) => res.send('add book'));

Middleware

Middleware são funções que rodam durante o ciclo da requisição, recebendo req, res e next. Chame next() para continuar ao próximo handler. app.use monta middleware globalmente ou num prefixo de caminho. Middleware de tratamento de erros tem 4 argumentos (err primeiro) e deve ser registrado por último.

nodejs
// middleware: (req, res, next) => {}
app.use(express.json());          // parse JSON bodies
app.use(express.static('public'));// serve static files
app.use((req, res, next) => {     // custom logger
  console.log(req.method, req.url);
  next();                         // pass control forward
});

// mounted on a path
app.use('/api', (req, res, next) => {
  req.apiCall = true;
  next();
});

// error-handling middleware (4 args)
app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(500).send('Server Error');
});

Dados da Requisição

O Express analisa corpos só se você montar o middleware certo: express.json() para JSON, express.urlencoded() para formulários, multer para uploads de arquivos. req.params (segmentos de URL), req.query (query string) e req.body (payload analisado) são as três principais fontes de dados de requisição.

nodejs
// JSON body (needs express.json() middleware)
app.post('/api', (req, res) => {
  console.log(req.body);          // parsed JSON object
});

// URL params and query
app.get('/u/:id', (req, res) => {
  const { id } = req.params;
  const { tab } = req.query;
});

// form data (urlencoded)
app.use(express.urlencoded({ extended: true }));
app.post('/form', (req, res) => res.json(req.body));

// file uploads: use multer middleware
// const upload = multer({ dest: 'uploads/' });
// app.post('/upload', upload.single('file'), handler);

// headers & cookies
req.headers['user-agent'];
req.cookies;        // needs cookie-parser

Servindo Arquivos Estáticos

express.static serve arquivos de um diretório. Monte múltiplas vezes para comportamento de fallback, ou prefixe com um caminho. Opções como maxAge definem headers de cache. Ele detecta tipos MIME automaticamente e suporta requisições de intervalo para vídeo/áudio. Sempre use caminhos absolutos para evitar bugs dependentes do cwd.

nodejs
const path = require('path');

// serve files from /public at /
app.use(express.static('public'));
// GET /style.css -> public/style.css

// mount at a prefix
app.use('/static', express.static('public'));
// GET /static/style.css -> public/style.css

// multiple directories (fallthrough)
app.use(express.static('public'));
app.use(express.static('uploads'));

// absolute path + options
app.use(express.static(path.join(__dirname, 'public'), {
  maxAge: '1d',
  setHeaders: (res, filePath) => {
    if (filePath.endsWith('.html')) res.setHeader('Cache-Control', 'no-cache');
  }
}));

Tratamento de Erros e Router

Passe um erro a next(err) ou lance dentro de um handler assíncrono para acionar o middleware de tratamento de erros. Registre um handler central de 4 argumentos por último. express.Router() modulariza rotas em arquivos separados — monte-os com app.use('/prefixo', router) para compor uma API grande de forma limpa.

nodejs
// throw to jump to error middleware
app.get('/broken', (req, res, next) => {
  const err = new Error('boom');
  err.status = 400;
  next(err);              // or throw err (Express 4+)
});

// centralized error handler (last middleware)
app.use((err, req, res, next) => {
  const status = err.status || 500;
  res.status(status).json({ error: err.message });
});

// modular routing with express.Router()
const router = express.Router();
router.get('/', (req, res) => res.send('api root'));
router.get('/users', (req, res) => res.send('users'));
app.use('/api', router);  // mount at /api
08

Streams

Streams Readable

Um stream Readable produz dados. Em modo flowing, os eventos 'data' empurram chunks automaticamente; em modo paused, você chama read() explicitamente. Sempre trate 'error' — eventos de erro não tratados derrubam o processo. highWaterMark controla o tamanho do buffer interno.

nodejs
const fs = require('fs');

// create a readable stream from a file
const rs = fs.createReadStream('big.log', { highWaterMark: 64 * 1024 });

// 'data' mode (flowing)
rs.on('data', chunk => {
  console.log('got', chunk.length, 'bytes');
});
rs.on('end', () => console.log('done'));
rs.on('error', err => console.error(err));

// paused mode: pull on demand
rs.on('readable', () => {
  let chunk;
  while ((chunk = rs.read()) !== null) {
    process(chunk);
  }
});

Streams Writable

Um stream Writable consome dados. write() retorna false quando o buffer interno está cheio — espere o evento 'drain' antes de escrever mais, para respeitar a contrapressão (backpressure). end() sinaliza que não há mais dados; 'finish' dispara depois que tudo é descarregado. process.stdout é ele próprio um stream writable.

nodejs
const fs = require('fs');
const ws = fs.createWriteStream('out.log');

// write returns false when the buffer is full (backpressure)
const ok = ws.write('line\n');
if (!ok) ws.once('drain', () => writeMore());

// signals completion
ws.end('final line\n');
ws.on('finish', () => console.log('all data flushed'));
ws.on('error', err => console.error(err));

// process.stdout is a writable stream
process.stdout.write('hello');

pipe e pipeline

pipe() encaminha um Readable a um Writable com contrapressão automática. stream.pipeline (prefira a versão de promises) encadeia múltiplos streams E propaga erros corretamente e faz a limpeza — .pipe() sozinho vaza recursos em erros no meio do stream. Sempre prefira pipeline a cadeias manuais de .pipe().

nodejs
const fs = require('fs');
const { pipeline } = require('stream/promises');

// pipe: readable -> writable (auto backpressure)
fs.createReadStream('in.txt')
  .pipe(fs.createWriteStream('out.txt'));

// pipeline: chain transforms, with error handling
const { Transform } = require('stream');
const upper = new Transform({
  transform(chunk, enc, cb) { cb(null, chunk.toString().toUpperCase()); }
});

await pipeline(
  fs.createReadStream('in.txt'),
  upper,
  fs.createWriteStream('out.txt')
);
// pipeline rejects on error, unlike .pipe()

Streams Transform

Um stream Transform lê a entrada, processa-a e emite saída transformada — perfeito para analisar, comprimir ou criptografar num pipeline. Implemente transform(chunk, enc, cb) e opcionalmente flush(cb). objectMode permite empurrar objetos em vez de Buffers. zlib e crypto fornecem transforms prontos.

nodejs
const { Transform } = require('stream');

// a Transform is both Readable and Writable
const csvToJson = new Transform({
  objectMode: false,
  transform(chunk, encoding, callback) {
    // convert each chunk
    const lines = chunk.toString().trim().split('\n');
    const json = lines.map(l => JSON.stringify(l.split(','))).join('\n');
    callback(null, json + '\n');
  },
  flush(callback) {
    callback(null, ']\n'); // finalize
  }
});

process.stdin.pipe(csvToJson).pipe(process.stdout);

// built-in transforms: zlib, crypto streams
const { createGzip } = require('zlib');
fs.createReadStream('log').pipe(createGzip()).pipe(fs.createWriteStream('log.gz'));

Modos de Stream e Backpressure

Streams alternam entre modos flowing e paused via pause()/resume(). Backpressure significa que um consumidor lento sinaliza ao produtor para desacelerar — a iteração assíncrona (for await) trata isso automaticamente ao aguardar cada chunk, o padrão moderno mais limpo. Sempre defina uma codificação para receber strings em vez de Buffers.

nodejs
const rs = fs.createReadStream('huge.bin');

// switch between modes
rs.pause();
rs.resume();
rs.setEncoding('utf8');

// respect backpressure manually
function writeChunk(ws, data) {
  if (!ws.write(data)) {
    rs.pause();
    ws.once('drain', () => rs.resume());
  }
}

// async iteration (Node 10+) — cleanest pattern
async function consume() {
  for await (const chunk of rs) {
    await handle(chunk);  // naturally respects backpressure
  }
}
consume();

Streams Personalizados

Subclasseie Readable/Writable/Duplex e implemente _read/_write, ou use o mais simples Readable.from() para dados que você já tem. push(null) sinaliza fim do stream. Streams Duplex são legíveis E graváveis de forma independente (como sockets TCP); Transform é um Duplex em que a saída deriva da entrada.

nodejs
const { Readable, Writable, Duplex } = require('stream');

// custom Readable: generate a counter
const counter = new Readable({
  read() {
    if (++this._n > 10) this.push(null);  // end
    else this.push(String(this._n));
  }
});
counter._n = 0;
counter.pipe(process.stdout);

// from an array / async iterable
Readable.from(['a', 'b', 'c']).pipe(process.stdout);

// a Duplex: both readable and writable (e.g. a socket)
class Echo extends Duplex {
  _read() {}
  _write(chunk, enc, cb) { this.push(chunk); cb(); }
}
09

Buffer

Criando Buffers

Buffer.alloc cria um buffer preenchido com zeros (seguro). Buffer.allocUnsafe pula a zeragem por velocidade, mas pode vazar memória antiga — use-o só quando for sobrescrever cada um dos bytes. Buffer.from converte strings/arrays/buffers. O construtor legado 'new Buffer()' está obsoleto por questões de segurança.

nodejs
// allocate zeroed bytes (SAFE)
const b1 = Buffer.alloc(8);            // <Buffer 00 00 00 00 00 00 00 00>

// allocate WITHOUT zeroing (faster, may contain old memory)
const b2 = Buffer.allocUnsafe(8);      // random old data!

// from a string with encoding
const b3 = Buffer.from('hello', 'utf8');
// <Buffer 68 65 6c 6c 6f>

// from an array of bytes
const b4 = Buffer.from([0x48, 0x49]);  // 'HI'

// from another buffer (copy)
const b5 = Buffer.from(b3);

// NEVER use new Buffer() — deprecated and unsafe

Leitura e Escrita

Buffers guardam bytes crus. Use funções de leitura/escrita com tamanhos explícitos (UInt8/16/32) e endianidade (BE/LE). Big-endian é a ordem de bytes de rede; little-endian é comum em x86. toString(encoding, start, end) decodifica bytes numa string. Sempre passe um offset para não sobrescrever bytes anteriores.

nodejs
const buf = Buffer.alloc(8);

// write numeric values at an offset
buf.writeUInt8(255, 0);       // 1 byte
buf.writeUInt16BE(0x1234, 1); // 2 bytes, big-endian
buf.writeInt32LE(1000, 3);    // 4 bytes, little-endian

// read them back
buf.readUInt8(0);             // 255
buf.readUInt16BE(1);          // 0x1234
buf.readInt32LE(3);           // 1000

// string read/write
buf.write('Hi', 0, 'utf8');
buf.toString('utf8', 0, 2);   // 'Hi'

Concat e Compare

Buffer.concat une um array de buffers (uma dica opcional de comprimento total melhora o desempenho). equals/compare permitem comparar sequências de bytes; indexOf/includes acham sub-buffers — úteis em protocolos binários. copy(target, targetStart, sourceStart, sourceEnd) copia uma fatia para outro buffer.

nodejs
const a = Buffer.from('foo');
const b = Buffer.from('bar');

// concatenate buffers
const c = Buffer.concat([a, b]);   // 'foobar'
Buffer.concat([a, b], 6);          // total length hint

// compare
Buffer.compare(a, b);        // -1 (a < b), 0, or 1
a.equals(b);                  // false

// find a sub-buffer
const big = Buffer.from('hello world');
big.indexOf(Buffer.from('world'));   // 6
big.includes(Buffer.from('hello'));  // true

// copy bytes
const target = Buffer.alloc(5);
big.copy(target, 0, 0, 5);   // copy first 5 bytes

Codificações

Codificações mapeiam entre strings e bytes. utf8 é o padrão para texto. base64/hex são comuns para binário-em-texto (data URLs, hashes, transporte). Buffer.byteLength dá o tamanho em bytes (caracteres multibyte contam mais de um byte em utf8) — use-o ao dimensionar buffers, não string.length.

nodejs
const text = 'Hello, 世界';

// string -> buffer (encode)
const utf8 = Buffer.from(text, 'utf8');
const base64 = Buffer.from(text).toString('base64');
const hex = Buffer.from(text).toString('hex');
const latin1 = Buffer.from(text, 'latin1');

// buffer -> string (decode)
utf8.toString('utf8');     // 'Hello, 世界'
Buffer.from(base64, 'base64').toString('utf8');
Buffer.from(hex, 'hex').toString('utf8');

// common encodings: utf8, utf16le, latin1, ascii,
//   base64, base64url, hex
Buffer.byteLength('世界', 'utf8');  // 6 bytes (not 2)

Buffer e TypedArrays

Buffer estende Uint8Array, então funciona onde quer que TypedArrays funcionem. Buffer.from(arrayBuffer) compartilha memória (sem cópia) — mas um Buffer pode fatiar um ArrayBuffer maior em pool, então sempre respeite byteOffset/byteLength ao criar views. Isso permite misturar APIs de Buffer com DataView para acesso numérico fino.

nodejs
// Buffer is a subclass of Uint8Array
const buf = Buffer.from([1, 2, 3]);
buf instanceof Uint8Array;  // true

// share memory with TypedArrays without copying
const u8 = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
view.getInt32(0);

// Buffer from an ArrayBuffer
const ab = new ArrayBuffer(8);
const buf2 = Buffer.from(ab);

// note: a Buffer's underlying buffer may be larger
// (allocUnsafe pools) -> always use byteOffset

Slice, Fill, Swap

subarray (ou slice) retorna uma view que compartilha a memória original — mutações afetam ambos. fill escreve um byte ou string repetida pelo buffer. swap16/swap32 invertem a ordem dos bytes no próprio local, para conversão de endianidade. Buffers são iteráveis, produzindo cada valor de byte 0–255.

nodejs
const buf = Buffer.from('abcdef');

// slice shares memory (no copy) — like subarray
const s = buf.subarray(1, 4);   // 'bcd'
s[0] = 88;                      // mutates buf too -> 'aXcdef'

// fill with a value or pattern
Buffer.alloc(4).fill(0xff);            // <Buffer ff ff ff ff>
Buffer.alloc(6).fill('ab');            // 'ababab'

// reverse byte order in place (for endianness swaps)
const n = Buffer.from([0x01, 0x02, 0x03, 0x04]);
n.swap16();  // swaps pairs: <Buffer 02 01 04 03>

// iterate with for...of
for (const byte of buf) console.log(byte);  // 97, 98, ...
10

EventEmitter

Criando e Emitindo Eventos

EventEmitter é o núcleo de pub/sub do Node. emit(nomeEvento, ...args) dispara um evento; on() assina. Muitas classes embutidas (streams, servidor http) o estendem. Nomes de eventos são strings arbitrárias, embora 'error' seja especial. Listeners são chamados sincronamente na ordem de registro.

nodejs
const { EventEmitter } = require('events');

class Clock extends EventEmitter {
  start() {
    this.emit('start', Date.now());          // emit with args
    setInterval(() => this.emit('tick', new Date()), 1000);
  }
}

const clock = new Clock();
clock.on('tick', date => console.log('tick', date));
clock.on('start', ts => console.log('started at', ts));
clock.start();

// on() == addListener; once() fires only once

once e removeListener

once() registra um listener que se remove automaticamente após disparar — ótimo para configuração única. Para remover um listener, você precisa guardar a referência exata da função (arrow functions criam novas referências a cada vez). removeAllListeners limpa os listeners de um ou de cada um dos eventos. off é um apelido para removeListener.

nodejs
const ee = new EventEmitter();

// once: auto-removed after first fire
ee.once('init', () => console.log('init fired'));

// remove a specific listener (need the same function ref)
const handler = () => console.log('hi');
ee.on('msg', handler);
ee.off('msg', handler);          // off() == removeListener

// remove all listeners for an event (or all events)
ee.removeAllListeners('msg');
ee.removeAllListeners();         // everything

// inspect
ee.listenerCount('msg');
ee.eventNames();                 // ['msg', 'init']

Eventos de Erro

Se um evento 'error' é emitido e NENHUM listener está registrado, o Node lança e derruba o processo. Sempre anexe um handler de erro a EventEmitters — especialmente streams e servidores HTTP. captureRejections (Node 12+) roteia promises rejeitadas de listeners assíncronos ao evento 'error'.

nodejs
const ee = new EventEmitter();

// 'error' is special: if unhandled, it CRASHES the process
ee.on('error', err => {
  console.error('caught:', err.message);
});

// later, emit an error safely
ee.emit('error', new Error('something broke'));

// guard against crashes from unhandled errors
// (monitor with the static capture)
EventEmitter.captureRejections = true; // for async handlers

// always register an error listener on streams/http

Listeners Assíncronos

EventEmitter chama listeners sincronamente, então a promise de um listener assíncrono não é aguardada — emit() retorna antes de ela se resolver. Use once(ee, nome) para aguardar um único evento como promise. Habilite captureRejections para que um listener assíncrono rejeitado acione o evento 'error' em vez de se perder silenciosamente.

nodejs
const ee = new EventEmitter();

// listeners run synchronously; await doesn't pause the chain
ee.on('save', async () => {
  await fs.promises.writeFile('x', 'y');
  console.log('saved');
});
ee.emit('save');  // returns before the await finishes

// wait for async listeners in sequence
const { once } = require('events');
async function waitForReady() {
  await once(ee, 'ready');   // promise resolves on first 'ready'
  console.log('now ready');
}

// handle async errors properly
EventEmitter.captureRejections = true;
ee.on('job', async () => { throw new Error('boom'); });
ee.on('error', err => console.error(err));

Nomes de Eventos e newListener

newListener e removeListener são eventos especiais emitidos quando listeners são adicionados/removidos — úteis para hooks ou profiling. setMaxListeners eleva o limite de detecção de vazamento (padrão 10); o aviso geralmente significa que você esqueceu de limpar listeners. Use Symbols ou constantes para nomes de eventos, para evitar erros de digitação.

nodejs
const ee = new EventEmitter();

// special events fired by EventEmitter itself
ee.on('newListener', (event, listener) => {
  console.log('listener added for', event);
});
ee.on('removeListener', (event, listener) => {
  console.log('listener removed for', event);
});

// limit listener count to catch leaks
ee.setMaxListeners(20);
ee.getMaxListeners();          // 20
// MaxListenersExceededWarning fires if exceeded

// convention: camelCase event names, 'error' reserved
// prefer symbols/const strings to avoid typos
const READY = Symbol('ready');
ee.emit(READY);
11

Processos Filhos

exec (shell, bufferizado)

exec() roda um comando via shell e bufferiza stdout/stderr — melhor para comandos curtos em que você quer toda a saída de uma vez. Ele cria um shell, então expande globs e pipes. NUNCA interpole entrada do usuário na string de comando — isso é uma vulnerabilidade de injeção de comando; use spawn com um array de args.

nodejs
const { exec } = require('child_process');

// runs a command in a shell, buffers all output
exec('ls -la', (err, stdout, stderr) => {
  if (err) { console.error('failed:', err); return; }
  console.log(stdout);    // full stdout as a string
  console.error(stderr);
});

// promisified (Node 12+)
const { promisify } = require('util');
const execP = promisify(exec);
const { stdout } = await execP('git rev-parse HEAD');

// WARNING: shell interpolation = injection risk!
// NEVER: exec(`rm ${userInput}`)

spawn (streaming, sem shell)

spawn() lança um processo com um array de args (sem shell) e transmite stdout/stderr — seguro e eficiente em memória para saída grande ou de longa duração. Como os args são passados direto (sem shell), não há expansão de globs nem risco de injeção. Conecte os streams filhos a outros streams com pipe para pipelines.

nodejs
const { spawn } = require('child_process');

// no shell by default -> safe, stream-based
const child = spawn('ls', ['-la', '/tmp']);

child.stdout.on('data', chunk => process.stdout.write(chunk));
child.stderr.on('data', chunk => process.stderr.write(chunk));
child.on('close', code => console.log('exit code', code));
child.on('error', err => console.error('failed to spawn', err));

// pipe streams directly
const gzip = spawn('gzip');
process.stdin.pipe(gzip.stdin);
gzip.stdout.pipe(process.stdout);

execFile e fork

execFile roda um executável sem shell — mais seguro que exec para rodar um binário conhecido com argumentos. fork() lança um processo Node e abre um canal IPC embutido (send/on('message')), a base para cluster e para passagem de mensagens tipo worker_threads entre processos Node.

nodejs
const { execFile, fork } = require('child_process');

// execFile: like exec but no shell (safer, slight overhead saving)
execFile('node', ['--version'], (err, stdout) => {
  console.log(stdout.trim());   // v20.x.x
});

// fork: spawn another Node process with an IPC channel
const worker = fork('./worker.js');
worker.send({ task: 'compute', n: 100 });
worker.on('message', msg => console.log('result:', msg));
worker.on('exit', code => console.log('worker exited', code));

// in worker.js:
// process.on('message', msg => { process.send(result); });

stdio e Argumentos

stdio controla os streams padrão do filho: 'inherit' compartilha o terminal do pai (ótimo para scripts npm), 'ignore' descarta, 'pipe' captura. detached + unref() lança um processo de fundo que sobrevive ao pai. Passe argumentos como array — o spawn os cita para você, então espaços e caracteres especiais são seguros.

nodejs
const { spawn } = require('child_process');

// control stdio: 'pipe' (default), 'inherit', 'ignore', or fd
const child = spawn('npm', ['test'], {
  stdio: 'inherit'     // child uses parent's stdin/stdout/stderr
});

// per-stream: [stdin, stdout, stderr]
spawn('cat', [], { stdio: ['pipe', process.stdout, 'ignore'] });

// set env, cwd, and detached background process
const bg = spawn('node', ['server.js'], {
  cwd: '/app',
  env: { ...process.env, NODE_ENV: 'production' },
  detached: true          // runs independently of parent
});
bg.unref();               // let parent exit without waiting

// pass arguments safely as array (no shell parsing)
spawn('echo', ['hello world']);  // one arg, no quotes needed

Códigos de Saída e Sinais

O evento 'exit' reporta code (null se morto por sinal) e signal (null para saída normal). 'close' dispara depois que cada um dos streams stdio fecha — use-o quando você conectou a saída com pipe e precisa saber que os streams foram descarregados. kill() envia um sinal; SIGTERM é gracioso, SIGKILL não pode ser capturado.

nodejs
const child = spawn('sleep', ['60']);

// 'exit' fires with code + signal
child.on('exit', (code, signal) => {
  if (code === 0) console.log('success');
  else if (signal) console.log('killed by', signal);
  else console.log('failed with code', code);
});

// send a signal to the child (SIGTERM by default)
setTimeout(() => child.kill('SIGTERM'), 1000);
child.kill();             // default SIGTERM
child.kill('SIGKILL');    // force-kill (cannot be caught)

// 'close' vs 'exit': 'close' fires after streams are closed
child.on('close', code => console.log('streams closed', code));

// check if process is still running
child.killed;             // true after kill() called
12

Cluster

Clustering Básico

cluster permite bifurcar múltiplos processos Node compartilhando uma porta, escalando pelos núcleos de CPU. O primário bifurca workers (tipicamente os.cpus().length). Cada worker é um processo Node completo rodando o mesmo script. Reinicie workers no 'exit' para resiliência. Use cluster.isPrimary (antes isMaster) para ramificar a lógica.

nodejs
const cluster = require('cluster');
const http = require('http');
const os = require('os');

if (cluster.isPrimary) {            // old: isMaster
  // fork one worker per CPU core
  for (let i = 0; i < os.cpus().length; i++) cluster.fork();

  cluster.on('exit', (worker, code) => {
    console.log(`worker ${worker.process.pid} died`);
    cluster.fork();                 // restart it
  });
} else {
  // workers share the same port
  http.createServer((req, res) => res.end('hi'))
    .listen(3000);
  console.log('worker started', process.pid);
}

Gestão de Workers

O primário acompanha workers via eventos 'online' (processo iniciado), 'listening' (servidor vinculado), 'disconnect' e 'exit'. disconnect() drena conexões antes de matar o worker — use-o para recarregamentos sem indisponibilidade. cluster.workers mapeia IDs de workers a objetos Worker, para que você possa enviar mensagens ou fechá-los.

nodejs
cluster.on('online', worker => {
  console.log('worker responsive', worker.id);
});

cluster.on('listening', (worker, address) => {
  console.log('worker bound to', address.port);
});

cluster.on('disconnect', worker => {
  console.log('worker disconnected', worker.id);
});

// gracefully shut down a worker
const w = cluster.workers[1];
w.disconnect();            // stop accepting connections, then exit
w.send('shutdown');        // custom message

// iterate all workers
for (const id in cluster.workers) {
  cluster.workers[id].send({ cmd: 'reload' });
}

Porta de Servidor Compartilhada

Cada um dos workers escuta a mesma porta; o primário balanceia as conexões de entrada. SCHED_RR (round-robin, padrão na maioria das plataformas) distribui uniformemente; SCHED_NONE deixa para o SO. O estado NÃO é compartilhado entre workers — use Redis ou banco de dados para sessões/cache compartilhados.

nodejs
const cluster = require('cluster');
const http = require('http');

if (cluster.isPrimary) {
  cluster.schedulingPolicy = cluster.SCHED_RR;  // round-robin (default on non-Windows)
  cluster.fork();
  cluster.fork();
} else {
  // all workers call listen(3000) — primary load-balances
  http.createServer((req, res) => {
    res.end(`handled by ${process.pid}`);
  }).listen(3000);
}

// SCHED_RR: primary distributes connections (default)
// SCHED_NONE: OS balances (may be uneven)

Ciclo de Vida de Workers e IPC

cluster.fork() abre um canal IPC (como child_process.fork): worker.send e process.on('message') trocam JSON entre primário e workers. Use-o para distribuir tarefas ou sinalizar desligamento gracioso. Para trabalho pesado de CPU, considere também worker_threads, que compartilham memória e evitam o custo do IPC.

nodejs
// primary -> worker messaging
if (cluster.isPrimary) {
  const worker = cluster.fork();
  worker.on('message', msg => console.log('from worker:', msg));
  worker.send({ task: 'heavy-compute' });
} else {
  process.on('message', msg => {
    console.log('from primary:', msg);
    // do work, then report back
    process.send({ done: true, result: 42 });
  });
}

// graceful shutdown signal
process.on('message', msg => {
  if (msg === 'shutdown') {
    server.close(() => process.exit(0));
  }
});

Reload Gracioso (Zero Downtime)

Um reinício rolando recarrega workers um de cada vez, para que o app nunca caia: desconecte um worker (ele para de aceitar novas conexões), espere que ele saia após drenar, depois bifurque um substituto. Acione com SIGHUP. Sempre combine com uma mensagem de 'shutdown' por worker, para que cada worker feche seu servidor e só saia depois que requisições em andamento terminem.

nodejs
// rolling restart: reload workers one at a time
function reload() {
  const workers = Object.values(cluster.workers || {});
  let i = 0;
  const next = () => {
    if (i >= workers.length) return;
    const w = workers[i++];
    w.send('shutdown');                 // tell worker to drain
    w.disconnect();                     // stop accepting connections
    w.once('exit', () => {
      cluster.fork();                   // replacement ready
      next();                           // move to the next
    });
  };
  next();
}

// trigger reload on SIGHUP
process.on('SIGHUP', reload);

// in the worker: finish in-flight requests then exit
process.on('message', msg => {
  if (msg === 'shutdown') server.close(() => process.exit(0));
});
13

Programação Assíncrona

Callbacks e Convenção Error-First

O padrão assíncrono clássico do Node é o callback error-first: o primeiro argumento é um erro (null em sucesso), os seguintes são resultados. Sempre verifique err primeiro e retorne cedo em caso de falha. Esse estilo escala mal com aninhamento — conhecido como callback hell — então código moderno usa Promises e async/await.

nodejs
// Node callbacks: (err, result) => {}
const fs = require('fs');

fs.readFile('data.txt', 'utf8', (err, data) => {
  if (err) return console.error('read failed', err);
  console.log(data);
});

// custom error-first function
function divide(a, b, cb) {
  if (b === 0) return cb(new Error('divide by zero'));
  cb(null, a / b);
}

divide(10, 2, (err, result) => {
  if (err) return console.error(err);
  console.log(result);   // 5
});

Promises

Uma Promise representa um valor futuro. then() trata o sucesso, catch() a rejeição, finally() roda em ambos os casos. Encadeie then() para transformar valores sequencialmente. util.promisify converte uma função de callback error-first numa que retorna Promise — ponte de APIs legadas para async/await.

nodejs
// create a promise
const p = new Promise((resolve, reject) => {
  setTimeout(() => resolve('done'), 100);
});

// consume with then/catch/finally
p.then(val => console.log(val))      // 'done'
 .catch(err => console.error(err))
 .finally(() => console.log('settled'));

// chain transforms
fetch(url)
  .then(r => r.json())
  .then(data => render(data));

// convert callback APIs
const { promisify } = require('util');
const readFile = promisify(fs.readFile);
const text = await readFile('x.txt', 'utf8');

async/await

async/await faz código assíncrono parecer síncrono. Uma função async retorna uma Promise; await pausa até ela se resolver. Envolva chamadas aguardadas em try/catch para tratar rejeições. Top-level await é permitido em ES Modules e (com uma flag) em CommonJS, eliminando a necessidade de um wrapper async IIFE.

nodejs
// async functions always return a Promise
async function loadUser(id) {
  const res = await fetch(`/api/users/${id}`);
  if (!res.ok) throw new Error('not found');
  return res.json();
}

// consume with try/catch
try {
  const user = await loadUser(5);
  console.log(user);
} catch (err) {
  console.error('failed:', err);
}

// top-level await works in ESM and CommonJS (Node 14.8+)
const config = await loadConfig();

Promise.all e allSettled

Promise.all roda promises em paralelo e resolve com um array de resultados, mas rejeita imediatamente se QUALQUER promise rejeitar (falha rápida) — use quando todas devem ter sucesso. Promise.allSettled espera cada promise independentemente do resultado, retornando objetos {status, value/reason} — melhor quando sucesso parcial é aceitável.

nodejs
// all: run in parallel, reject fast on first failure
const [a, b, c] = await Promise.all([
  fetch('/a').then(r => r.json()),
  fetch('/b').then(r => r.json()),
  fetch('/c').then(r => r.json())
]);

// allSettled: wait for ALL, never rejects
const results = await Promise.allSettled([
  fetch('/x'),
  fetch('/y'),
  fetch('/z')
]);
results.forEach(r => {
  if (r.status === 'fulfilled') console.log(r.value);
  else console.error(r.reason);   // rejected reason
});

Promise.race e Promise.any

Promise.race resolve OU rejeita com a primeira promise a se resolver — útil para timeouts e corrida entre espelhos. Promise.any resolve com o primeiro sucesso e só rejeita (AggregateError) se todas as promises falharem — ideal para endpoints redundantes em que uma resposta saudável basta.

nodejs
// race: first to SETTLE (resolve or reject) wins
const fastest = await Promise.race([
  fetch('/primary'),
  fetch('/mirror'),
  timeout(5000)
]);

// any: first to FULFILL wins; rejects only if ALL reject
const alive = await Promise.any([
  fetch('/node1'),
  fetch('/node2'),
  fetch('/node3')
]);

// implement a timeout with race
function withTimeout(p, ms) {
  return Promise.race([
    p,
    new Promise((_, reject) =>
      setTimeout(() => reject(new Error('timeout')), ms))
  ]);
}

Sequencial vs Paralelo

Aguardar num loop roda sequencialmente (lento). Mapeie para um array de promises e aplique Promise.all para paralelismo (rápido, mas concorrência sem limite pode sobrecarregar recursos). Um pool que limita a concorrência estrangula o trabalho paralelo — essencial ao chamar APIs com limite de taxa ou fazer I/O pesado sobre milhares de itens.

nodejs
// SEQUENTIAL: one after another (slow)
const results = [];
for (const url of urls) {
  results.push(await fetch(url).then(r => r.json()));
}

// PARALLEL: fire all, await together (fast)
const results = await Promise.all(
  urls.map(u => fetch(u).then(r => r.json()))
);

// THROTTLED: limit concurrency with a pool
async function mapLimit(items, limit, fn) {
  const ret = [];
  const executing = [];
  for (const item of items) {
    const p = Promise.resolve().then(() => fn(item));
    ret.push(p);
    if (executing.push(p) >= limit) {
      await Promise.race(executing);
      executing.splice(executing.findIndex(x => x === p), 1);
    }
  }
  return Promise.all(ret);
}
14

Tratamento de Erros

try/catch/finally

try/catch trata erros síncronos e (com await) rejeições assíncronas. finally sempre roda, mesmo com return/throw — use-o para limpeza, como fechar handles. Capture erros específicos verificando err.code e relance tudo que não reconhece, para que bugs inesperados apareçam em vez de serem engolidos.

nodejs
function parse(str) {
  try {
    return JSON.parse(str);
  } catch (err) {
    console.error('parse failed:', err.message);
    return null;
  } finally {
    console.log('cleanup always runs');
  }
}

// async errors need async catch
async function load() {
  try {
    const data = await fetchData();
    return data;
  } catch (err) {
    if (err.code === 'ENOENT') return defaultData();
    throw err;              // re-throw unknown errors
  }
}

Callbacks Error-First

Em callbacks error-first, sempre verifique err primeiro e retorne cedo — nunca use data quando err está definido. Ao embrulhar uma API de callback, encaminhe o erro ao seu próprio callback em vez de lançar (throws dentro de callbacks não podem ser capturados por quem chama). Envolva código síncrono que pode lançar (como JSON.parse) em try/catch.

nodejs
const fs = require('fs');

// ALWAYS check err first, return early
fs.readFile('missing.txt', 'utf8', (err, data) => {
  if (err) {
    console.error('could not read:', err.message);
    return;            // don't use data
  }
  console.log(data);
});

// propagate the error to your own caller
function readConfig(cb) {
  fs.readFile('config.json', 'utf8', (err, raw) => {
    if (err) return cb(err);
    try { cb(null, JSON.parse(raw)); }
    catch (e) { cb(e); }
  });
}

Exceções Não Capturadas

uncaughtException dispara para exceções síncronas que escapam de cada um dos handlers — o processo agora está corrompido; registre no log, feche o servidor e saia (deixe um gerenciador de processos reiniciá-lo). unhandledRejection dispara para promises esquecidas; desde o Node 15 elas derrubam o processo, então sempre adicione .catch() ou use await dentro de try/catch.

nodejs
// last-resort handler for sync exceptions
process.on('uncaughtException', err => {
  console.error('UNCAUGHT:', err);
  // the process is in an unknown state — restart it
  server.close(() => process.exit(1));
});

// rejected promises nobody awaited
process.on('unhandledRejection', (reason, promise) => {
  console.error('UNHANDLED REJECTION:', reason);
});

// Node 15+: unhandled rejections terminate the process
// always add .catch() or wrap in try/await

Classes de Erro Personalizadas

Subclasseie Error para adicionar campos estruturados (code, field, status) e distinguir tipos de erro com instanceof. Sempre defina this.name com o nome da classe (não é automático em alvos antigos) e chame super(message). Erros personalizados tornam os blocos catch legíveis: ramifique com instanceof em vez de casamento frágil de strings.

nodejs
// subclass Error to add context
class ValidationError extends Error {
  constructor(field, message) {
    super(message);
    this.name = 'ValidationError';
    this.field = field;
    this.code = 'VALIDATION_FAILED';
  }
}

function validate(email) {
  if (!email.includes('@')) {
    throw new ValidationError('email', 'invalid email');
  }
}

// branch on error type with instanceof
try {
  validate('no-at-sign');
} catch (err) {
  if (err instanceof ValidationError) {
    console.log(err.field, err.message);
  } else {
    throw err;
  }
}

Propriedades de Erro e cause

Cada Error tem message, name e stack. Adicione uma propriedade code para tratamento estável e legível por máquina (os próprios erros do Node usam códigos como ENOENT, EACCES). A opção cause do ES2022 (Node 16.9+) encadeia um erro subjacente, permitindo embrulhar falhas de baixo nível preservando o stack original para depuração.

nodejs
// built-in Error props
const e = new Error('something broke');
e.message;    // 'something broke'
e.stack;      // stack trace string
e.name;       // 'Error'

// add a code for machine-readable handling
const err = new Error('file missing');
err.code = 'ENOENT';
err.errno = -2;

// Error.cause (Node 16.9+) — chain underlying errors
try {
  JSON.parse(bad);
} catch (original) {
  throw new Error('config parse failed', { cause: original });
}

// inspect the cause
console.log(err.cause);            // the original SyntaxError

Domains e Limpeza

Use 'beforeExit' para limpeza assíncrona (pode adiar a saída) e 'exit' só para trabalho síncrono. Trate SIGTERM (desligamento de contêiner) e SIGINT (Ctrl-C) para drenar conexões antes de sair — adicione um timeout de saída forçada, para que uma conexão presa não mantenha o processo eternamente. Domains estão obsoletos; use try/catch e tratamento de erros assíncrono.

nodejs
// modern cleanup: 'beforeExit' for async, 'exit' for sync
process.on('beforeExit', async () => {
  await closeDbConnections();
});

process.on('exit', code => {
  // ONLY sync code allowed here — no async, no promises
  console.log('exiting with', code);
});

// graceful signal handling
const shutdown = sig => {
  console.log('got', sig);
  server.close(() => process.exit(0));
  setTimeout(() => process.exit(1), 5000).unref(); // force exit
};
process.on('SIGTERM', () => shutdown('SIGTERM'));
process.on('SIGINT', () => shutdown('SIGINT'));
15

Depuração

Funções do console

console oferece mais que log: table renderiza arrays de objetos, time/timeEnd mede durações, dir despeja um objeto com profundidade configurável, trace imprime um stack e count conta acionamentos. Use console.error (stderr) para que logs e erros possam ser separados em pipelines de produção.

nodejs
console.log('basic');              // stdout
console.error('oops');           // stderr
console.warn('careful');         // stderr

// formatted table
console.table([{ id: 1, n: 'A' }, { id: 2, n: 'B' }]);

// inspect an object in depth
console.dir(obj, { depth: null, colors: true });

// timing a block
console.time('loop');
for (let i = 0; i < 1e6; i++) {}
console.timeEnd('loop');         // loop: 3.2ms

// stack trace
console.trace('where am I');

// count calls
for (let i = 0; i < 3; i++) console.count('hit');

node inspect e DevTools

--inspect inicia o inspetor V8 para que o Chrome DevTools (chrome://inspect) ou o VS Code se conecte. --inspect-brk pausa na primeira linha para que você defina breakpoints antes do código de inicialização rodar. O clássico 'node inspect' é um depurador de terminal útil via SSH, onde um navegador não está disponível.

nodejs
# open Chrome DevTools debugger
node --inspect app.js
# visit chrome://inspect, click "inspect"

# pause on first line (break before anything runs)
node --inspect-brk app.js

# wait for a debugger client to attach
node --inspect-wait app.js

# the legacy CLI debugger (still works, no browser)
node inspect app.js
# > cont, step, next, breakpoints, repl

A Instrução debugger

A instrução debugger pausa a execução SOMENTE quando um depurador (DevTools ou VS Code) está conectado — caso contrário é uma no-op, segura para deixar no código. Combine com --inspect-brk para parar na inicialização. Para inspeção ad hoc, insira debugger; dentro de loops ou condições em vez de definir breakpoints pela UI.

nodejs
function findBug(arr) {
  let sum = 0;
  for (const n of arr) {
    debugger;        // pauses only when a debugger is attached
    sum += n;
  }
  return sum;
}

// run with --inspect-brk to hit the breakpoint
// node --inspect-brk app.js

// conditional breakpoints in DevTools/VSCode:
//   if (n > 100) { debugger; }

Depuração no VS Code

O depurador Node do VS Code (F5) lê .vscode/launch.json. "request": "launch" roda o programa com o inspetor embutido; "attach" conecta a um processo já iniciado com --inspect. skipFiles esconde as entranhas do Node do stepping. Use a flag "restart" ou o nodemon para relançar automaticamente ao mudar arquivos.

nodejs
// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug App",
      "program": "${workspaceFolder}/app.js",
      "skipFiles": ["<node_internals>/**"]
    },
    {
      "type": "node",
      "request": "attach",
      "name": "Attach by PID",
      "processId": "${command:PickProcess}"
    }
  ]
}

// F5 to start; set breakpoints in the editor
// "restart": true, "nodemon" for auto-restart on change

Avisos e Stack Traces

--trace-warnings imprime stacks para avisos do processo (vazamentos de memória, APIs obsoletas). --trace-deprecation revela uso de APIs legadas; --throw-deprecation transforma isso em erros duros, para CI mais rigoroso. --cpu-prof escreve um profile que você abre no Chrome DevTools para achar funções quentes. Eleve Error.stackTraceLimit para traces assíncronos mais profundos.

nodejs
# show stack traces for process warnings
node --trace-warnings app.js

# deprecation warnings (use --throw-deprecation to make them errors)
node --trace-deprecation app.js

# capture a stack trace manually
const e = new Error('here');
console.log(e.stack);

# show async stack traces (Node 12+ enabled by default)
Error.stackTraceLimit = 50;   // deeper traces

# profile CPU usage
node --cpu-prof app.js        # writes CPU.*.cpuprofile
# then load the file in Chrome DevTools
16

Crypto

Hashing (createHash)

createHash produz um digest de sentido único. SHA-256 é o padrão moderno para checksums e assinaturas; evite MD5/SHA-1 por segurança (propensos a colisões). Você pode alimentar dados incrementalmente e transmitir arquivos grandes sem bufferizar. digest('hex') retorna uma string hex; 'base64' também é comum. Hashing NÃO é armazenamento de senhas — use pbkdf2/scrypt.

nodejs
const crypto = require('crypto');

// common hashes: sha256, sha512, md5 (insecure!), sha1
const hash = crypto.createHash('sha256');
hash.update('hello');
hash.update(' world');        // can chain updates
console.log(hash.digest('hex'));
// b94d...  (64 hex chars)

// one-shot hashing
const h = crypto.createHash('sha256').update('data').digest('hex');
console.log(h);

// file hash (streaming)
const fs = require('fs');
const fhash = crypto.createHash('sha256');
fs.createReadStream('big.iso').on('data', c => fhash.update(c))
  .on('end', () => console.log(fhash.digest('hex')));

HMAC (createHmac)

HMAC assina dados com um segredo compartilhado, para que o receptor verifique integridade e autenticidade. É a base das assinaturas JWT e da verificação de webhooks (GitHub, Stripe). Sempre compare assinaturas com timingSafeEqual — um === comum vaza informação por diferenças de tempo que atacantes podem explorar.

nodejs
const crypto = require('crypto');

// HMAC = keyed hash (authenticity + integrity)
const secret = process.env.SECRET_KEY;
const hmac = crypto.createHmac('sha256', secret);
hmac.update('payload to sign');
const signature = hmac.digest('hex');

// verify a webhook signature (constant-time compare)
function verify(payload, receivedSig) {
  const expected = crypto.createHmac('sha256', secret)
    .update(payload).digest('hex');
  // timingSafeEqual prevents timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(receivedSig)
  );
}

Bytes Aleatórios

crypto.randomBytes produz dados aleatórios criptograficamente seguros — use para tokens, IDs e segredos. A forma assíncrona evita bloquear o event loop ao gerar muitos bytes. crypto.randomInt dá inteiros aleatórios sem viés, e randomUUID() gera UUIDs RFC-4122 v4. Nunca use Math.random() para nada relacionado a segurança.

nodejs
const crypto = require('crypto');

// async (preferred — doesn't block the event loop)
crypto.randomBytes(16, (err, buf) => {
  const token = buf.toString('hex');   // 32-char hex
});

// sync (blocks; fine for small sizes)
const id = crypto.randomBytes(8).toString('hex');

// random integer in [min, max)
const n = crypto.randomInt(1, 101);     // 1..100

// random UUID (Node 14.17+)
const uuid = crypto.randomUUID();
// '1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed'

// use crypto, NEVER Math.random() for secrets!

Criptografia (createCipheriv)

AES-256-GCM é a cifra simétrica recomendada — é autenticada, então adulterações são detectadas. O IV (nonce) precisa ser único por criptografia com uma dada chave (nunca reutilize); guarde-o junto ao texto cifrado. setAuthTag verifica a integridade ao descriptografar. Nunca use o createCipher obsoleto (deriva chaves de forma insegura) — sempre use createCipheriv com uma chave adequada.

nodejs
const crypto = require('crypto');
const algorithm = 'aes-256-gcm';

// AES-256-GCM (authenticated encryption) ----------------
const key = crypto.randomBytes(32);   // 256-bit key
const iv = crypto.randomBytes(12);    // 96-bit nonce

function encrypt(text) {
  const cipher = crypto.createCipheriv(algorithm, key, iv);
  const enc = Buffer.concat([cipher.update(text, 'utf8'), cipher.final()]);
  const tag = cipher.getAuthTag();    // GCM auth tag
  return { enc, tag };
}

function decrypt(enc, tag) {
  const decipher = crypto.createDecipheriv(algorithm, key, iv);
  decipher.setAuthTag(tag);           // verify integrity
  return Buffer.concat([decipher.update(enc), decipher.final()]).toString('utf8');
}

Hash de Senhas (pbkdf2, scrypt)

Faça hash de senhas com um KDF lento e salgado — nunca com um hash simples. pbkdf2 (ajuste as iterações para cima conforme o hardware melhora) e scrypt (dificuldade de memória, resistente a GPU) estão embutidos no Node. Guarde iterações, salt e hash juntos, para poder verificar e depois atualizar os parâmetros. Use timingSafeEqual para conferir hashes sem vazar informação de tempo.

nodejs
const crypto = require('crypto');

// PBKDF2: tuned with iterations
function hashPbkdf2(password) {
  const salt = crypto.randomBytes(16);
  const iterations = 100000;
  const hash = crypto.pbkdf2Sync(password, salt, iterations, 64, 'sha256');
  return `${iterations}.${salt.toString('hex')}.${hash.toString('hex')}`;
}

// scrypt: memory-hard, resistant to GPU/ASIC attacks
function hashScrypt(password) {
  const salt = crypto.randomBytes(16);
  const hash = crypto.scryptSync(password, salt, 64, { N: 16384 });
  return salt.toString('hex') + '.' + hash.toString('hex');
}

// verify: re-hash with the same salt and compare
function verify(password, stored) {
  const [iter, salt, hash] = stored.split('.');
  const computed = crypto.pbkdf2Sync(password, Buffer.from(salt, 'hex'),
    +iter, 64, 'sha256');
  return crypto.timingSafeEqual(Buffer.from(hash, 'hex'), computed);
}

Comparação Segura em Tempo

timingSafeEqual compara dois buffers em tempo constante, prevenindo ataques de timing em que um atacante infere um segredo byte a byte pelos atrasos de resposta. Ambos os buffers devem ter o mesmo comprimento (verifique primeiro, mas essa checagem de comprimento em si pode vazar o comprimento — para segredos, faça hash de ambos os lados antes). Use-o sempre que comparar tokens, assinaturas ou chaves de API.

nodejs
const crypto = require('crypto');

// NORMAL compare leaks via timing (returns early on first diff)
// 'secret' === userInput  // BAD for secrets

// timingSafeEqual takes equal-length Buffers
function safeEqual(a, b) {
  const bufA = Buffer.from(a);
  const bufB = Buffer.from(b);
  if (bufA.length !== bufB.length) return false;
  return crypto.timingSafeEqual(bufA, bufB);
}

// common use: API key check
function auth(req) {
  const provided = req.headers['x-api-key'] || '';
  return safeEqual(provided, process.env.API_KEY);
}
17

Módulo OS

Informações do Sistema

os expõe o ambiente hospedeiro. platform/arch/type identificam o SO para checagens de portabilidade. os.EOL dá a sequência de fim de linha da plataforma — use ao escrever arquivos de texto corretos por plataforma. hostname é o nome de rede da máquina, útil para registrar qual instância atendeu uma requisição.

nodejs
const os = require('os');

os.platform();    // 'linux', 'darwin', 'win32'
os.arch();        // 'x64', 'arm64'
os.type();        // 'Linux', 'Darwin', 'Windows_NT'
os.release();     // kernel version
os.hostname();    // machine hostname
os.uptime();      // seconds since boot
os.EOL;           // '\n' (POSIX) or '\r\n' (Windows)

// detect platform portably
const isWin = os.platform() === 'win32';
const isMac = os.platform() === 'darwin';

Informações de CPU

os.cpus() retorna um array de núcleos lógicos (hyperthreads incluídos), então seu comprimento é a dica certa de concorrência para cluster.fork. Cada entrada tem model, speed e times (user/sys/idle). loadavg reporta a carga do sistema (só Linux/macOS) — um valor acima de cpus().length sugere saturação.

nodejs
const os = require('os');

// logical core count (threads, not physical)
os.cpus().length;        // 8

// detailed per-core info
os.cpus().forEach((cpu, i) => {
  console.log(`core ${i}: ${cpu.model} @ ${cpu.speed}MHz`);
});

// 1/5/15-minute load averages (NOT on Windows)
os.loadavg();            // [0.45, 0.32, 0.28]

// set process scheduling priority
os.setPriority(os.constants.priority.PRIORITY_BELOW_NORMAL);

Memória

os.totalmem/freemem reportam a RAM do sistema, enquanto process.memoryUsage reporta o consumo deste processo. rss é a memória no nível do SO; heapUsed são os objetos JS vivos. Acompanhe heapUsed para vazamentos. Para converter bytes em MB, divida por 1024*1024 (1048576). Ajuste --max-old-space-size quando o heap crescer perto do limite.

nodejs
const os = require('os');

// system memory (bytes)
os.totalmem();          // e.g. 17179869184
os.freemem();           // currently free bytes

// process memory usage (bytes)
const m = process.memoryUsage();
m.rss;          // resident set size (total RAM held)
m.heapTotal;    // V8 heap allocated
m.heapUsed;     // V8 heap actually used
m.external;     // C++ objects bound to JS
m.arrayBuffers; // memory in ArrayBuffers

// human-readable
console.log(`heap: ${(m.heapUsed / 1048576).toFixed(1)} MB`);

Interfaces de Rede

os.networkInterfaces() lista cada interface de rede com seus endereços, MAC e família (IPv4/IPv6). A flag 'internal' marca loopback. É a forma portátil de descobrir o IP de LAN da máquina, para vincular servidores ou registrar logs. Cada interface pode ter múltiplos endereços (hosts multihomed).

nodejs
const os = require('os');

const nets = os.networkInterfaces();
for (const name of Object.keys(nets)) {
  for (const net of nets[name]) {
    console.log(`${name} ${net.family}: ${net.address} (${net.mac})`);
  }
}
// en0 IPv4: 192.168.1.10 (aa:bb:cc:...)
// lo IPv4: 127.0.0.1 (:::...)

// find this machine's LAN IPv4
function getLanIp() {
  for (const nets of Object.values(os.networkInterfaces())) {
    for (const n of nets) {
      if (n.family === 'IPv4' && !n.internal) return n.address;
    }
  }
  return '127.0.0.1';
}

Usuário e Caminhos

os.homedir retorna o diretório home do usuário e os.tmpdir a pasta temporária do sistema — ambos conscientes da plataforma, então prefira-os a caminhos fixados no código. os.userInfo dá a identidade do usuário atual. os.constants centraliza valores numéricos de sinal/errno/prioridade, para você não fixar números mágicos como 15 para SIGTERM.

nodejs
const os = require('os');

os.homedir();      // /home/alice  or C:\Users\alice
os.tmpdir();       // /tmp         or C:\Users\...\Temp
os.userInfo();     // { username, uid, gid, homedir, shell }
os.constants;      // signal/errno/priority constants

// errno constants map
os.constants.errno.ENOENT;   // -2
// signal constants
os.constants.signals.SIGTERM; // 15

// priority constants
os.constants.priority.PRIORITY_HIGH;

// build a portable temp path
const path = require('path');
const tmpFile = path.join(os.tmpdir(), 'app-' + Date.now() + '.log');
18

Process

process.argv

process.argv guarda os argumentos de linha de comando: argv[0] é o binário node, argv[1] é o script, e o resto são argumentos do usuário. Fatie os dois primeiros para obter só os argumentos do usuário. Para algo além de scripts de brinquedo, use um parser como minimist, yargs ou commander — eles tratam flags, tipos, padrões e texto de ajuda.

nodejs
// argv[0] = node path, argv[1] = script path, argv[2+] = args
// node app.js --port 3000 users.csv
console.log(process.argv);
// ['/usr/bin/node', '/app/app.js', '--port', '3000', 'users.csv']

const args = process.argv.slice(2);
console.log(args);  // ['--port', '3000', 'users.csv']

// minimal flag parsing
function parseArgs(arr) {
  const out = { _: [] };
  for (let i = 0; i < arr.length; i++) {
    if (arr[i].startsWith('--')) out[arr[i].slice(2)] = arr[++i];
    else out._.push(arr[i]);
  }
  return out;
}
// for real CLI use commander, yargs, or minimist

process.env

process.env guarda variáveis de ambiente como strings. Por convenção, PORT, NODE_ENV, DATABASE_URL e API_KEY vêm do ambiente, para que o mesmo código rode em ambientes diferentes. Use o pacote dotenv para carregar um arquivo .env no desenvolvimento. Nunca comite segredos — injete-os pelo ambiente do host/CI.

nodejs
// read environment variables
const port = process.env.PORT || 3000;
const dbUrl = process.env.DATABASE_URL;
const nodeEnv = process.env.NODE_ENV || 'development';

const isProd = process.env.NODE_ENV === 'production';

// set an env var (affects child processes too)
process.env.MY_VAR = 'value';

// load .env files (install: npm i dotenv)
// require('dotenv').config();

// enumerate everything
for (const [k, v] of Object.entries(process.env)) {
  console.log(k, '=', v);
}

process.exit e Códigos de Saída

process.exit(n) termina imediatamente, possivelmente antes de os buffers de I/O descarregarem — prefira definir process.exitCode e deixar o event loop drenar naturalmente. Saída 0 significa sucesso; não zero sinaliza falha a shells e CI. A convenção 128+N codifica terminação pelo sinal N (então SIGTERM dá 143).

nodejs
// exit immediately with a status code
process.exit(0);    // success
process.exit(1);    // general failure

// exit code is also settable
process.exitCode = 2;   // used if the loop ends naturally

// prefer setting exitCode + returning over process.exit()
// so async work can finish

// common conventions:
// 0  success
// 1  general error
// 2  misuse (bad args)
// 124 timeout (from the 'timeout' command)
// 128+N  killed by signal N (e.g. 143 = SIGTERM)

stdin / stdout / stderr

process.stdout e process.stderr são streams graváveis — write() não adiciona quebra de linha (diferente de console.log). stdin é um stream legível que você pode consumir com eventos 'data' ou iteração assíncrona (o padrão moderno mais limpo). Use stderr para diagnósticos, para que possa ser separado da saída real em pipes.

nodejs
// stdout/stderr are writable streams
process.stdout.write('no newline');
process.stdout.write('line\n');
console.log === process.stdout.write.bind(...); // roughly

// stdin is a readable stream
process.stdin.setEncoding('utf8');
process.stdin.on('data', chunk => console.log('got:', chunk));

// read all of stdin (async iteration)
async function readStdin() {
  let data = '';
  for await (const chunk of process.stdin) data += chunk;
  return data;
}

// ask a yes/no question
process.stdin.resume();
process.stdin.once('data', input => process.exit(input[0] === 'y'.charCodeAt(0) ? 0 : 1));

Eventos de Processo (Sinais)

'exit' dispara depois que o event loop esvazia — só código síncrono roda ali. 'beforeExit' pode rodar trabalho assíncrono e pode adiar a saída. Trate SIGINT (Ctrl-C) e SIGTERM (docker stop, kill) para fechar servidores e conexões de banco com elegância. Sempre defina um timeout de saída forçada, para que uma conexão presa não mantenha o processo para sempre.

nodejs
// lifecycle events
process.on('exit', code => {
  // sync only here — no async, no event loop
  console.log('bye, code', code);
});
process.on('beforeExit', () => {
  // async OK; can postpone exit
});

// signal handlers (Unix + Windows for SIGINT/SIGTERM)
process.on('SIGINT', () => {       // Ctrl-C
  console.log('graceful shutdown...');
  server.close(() => process.exit(0));
});
process.on('SIGTERM', () => {      // kill / docker stop
  server.close(() => process.exit(0));
});
process.on('SIGHUP', () => reloadConfig());

memoryUsage e uptime

process expõe identidade (pid, ppid, platform, version) e estatísticas de runtime (uptime, memoryUsage, cpuUsage). cwd() é o diretório de trabalho — chdir o muda, afetando a resolução de caminhos relativos. memoryUsage e cpuUsage são a base de endpoints de health check e métricas de autoscaling.

nodejs
// process info
process.pid;             // OS process ID
process.ppid;            // parent PID
process.platform;        // 'linux', 'darwin', 'win32'
process.version;         // 'v20.11.0'
process.versions;        // { v8, openssl, modules, ... }
process.cwd();           // current working directory
process.uptime();        // seconds since process started

// change directory
process.chdir('/tmp');

// memory snapshot
const m = process.memoryUsage();
console.log(m.rss, m.heapUsed);

// CPU usage of this process
const cpu = process.cpuUsage();
console.log(cpu.user, cpu.system);  // microseconds
19

Rede (net)

Servidor TCP

net.createServer cria um servidor TCP bruto. Cada conexão invoca o callback com um Socket (um stream Duplex). Leia com eventos 'data', escreva com socket.write. Sempre trate 'error' nos sockets ou o processo cai. TCP é a fundação sob o HTTP — útil para protocolos personalizados, jogos e proxies.

nodejs
const net = require('net');

const server = net.createServer(socket => {
  console.log('client connected', socket.remoteAddress);
  socket.write('welcome\n');

  socket.on('data', data => {
    socket.write('echo: ' + data);     // echo back
  });

  socket.on('end', () => console.log('client left'));
  socket.on('error', err => console.error('socket err', err));
});

server.listen(5000, () => {
  console.log('TCP server on port 5000');
});

// test with: nc localhost 5000  or  telnet localhost 5000

Cliente TCP

net.connect (apelido createConnection) abre um socket cliente TCP. O callback dispara na conexão; eventos 'data' entregam os bytes de entrada. Defina uma codificação para receber strings em vez de Buffers. Como qualquer stream, trate 'error' para evitar quedas. Sockets fecham automaticamente no 'end'; chame client.end() para meio-fechar o seu lado.

nodejs
const net = require('net');

// connect to a TCP server
const client = net.connect(5000, 'localhost', () => {
  console.log('connected');
  client.write('hello server\n');
});

client.setEncoding('utf8');
client.on('data', data => console.log('server said:', data));
client.on('end', () => console.log('disconnected'));
client.on('error', err => console.error(err));

// or with an options object + timeout
const c = net.createConnection({
  port: 5000,
  host: 'localhost',
  timeout: 5000
});

Eventos e Dados de Socket

TCP é um fluxo de bytes, não um protocolo de mensagens — um evento 'data' não equivale a uma mensagem; os dados podem ser divididos ou unidos. Você PRECISA enquadrar as mensagens você mesmo (prefixos de comprimento, delimitadores ou um parser). setKeepAlive detecta pares mortos, setTimeout mata conexões ociosas e 'drain' sinaliza que o buffer de escrita esvaziou.

nodejs
const net = require('net');

net.createServer(socket => {
  socket.setEncoding('utf8');
  socket.setKeepAlive(true, 30000);   // enable TCP keepalive
  socket.setTimeout(60000);           // idle timeout

  socket.on('data', chunk => {
    // TCP is a STREAM: chunks may split or merge messages.
    // Frame your protocol (length prefix, delimiter, etc.)
    console.log('received', chunk.length, 'bytes');
  });

  socket.on('timeout', () => socket.end());
  socket.on('close', hadError => console.log('closed', hadError));
  socket.on('drain', () => console.log('buffer drained'));
}).listen(5000);

Escrita e Meio-fechamento

socket.write respeita a contrapressão (retorna false quando cheio — espere 'drain'). end() meio-fecha: descarrega as escritas pendentes e envia FIN, enquanto continua lendo o par. destroy() mata o socket imediatamente. Use remoteAddress/remotePort para logs e controle de acesso. Pause/resume estrangulam um remetente rápido.

nodejs
const net = require('net');

net.createServer(socket => {
  // write() returns false when the buffer is full (backpressure)
  const ok = socket.write(bigPayload);
  if (!ok) socket.once('drain', writeMore);

  // half-close: send FIN, keep reading
  socket.end();   // writes any pending data, then closes our side
  // socket.end('final message\n'); // write + close

  // fully destroy the socket immediately
  socket.destroy();

  // pause/resume reading
  socket.pause();
  socket.resume();

  // address info
  socket.remoteAddress;  // '192.168.1.5'
  socket.remotePort;     // 54321
}).listen(5000);

Eventos do Servidor e IPC

Um net.Server emite 'connection' (por cliente), 'listening', 'error' (trate EADDRINUSE) e 'close'. listen pode receber um caminho para um socket Unix (ou named pipe no Windows) — IPC local rápido e seguro entre processos no mesmo host. server.close() para de aceitar novas conexões e espera as existentes terminarem.

nodejs
const net = require('net');

const server = net.createServer();
server.on('connection', socket => {});   // same as createServer cb
server.on('listening', () => console.log('bound'));
server.on('error', err => {
  if (err.code === 'EADDRINUSE') console.error('port taken');
});
server.on('close', () => console.log('server closed'));

server.listen(5000);

// Unix domain socket / named pipe (fast local IPC)
server.listen('/tmp/app.sock');
// Windows: server.listen('\\\\.\\pipe\\app');

// stop accepting, close idle connections
server.close(() => console.log('all done'));

// get bound address
server.address();   // { port: 5000, family: 'IPv4', address: '::' }
20

Timers e Utilitários

Timers (setTimeout, setInterval)

setTimeout roda uma vez após um atraso, setInterval repete. setImmediate roda depois dos eventos de I/O na mesma volta do loop. queueMicrotask roda ainda mais cedo, logo depois da operação atual. A ordem dentro de um loop é: microtasks primeiro, depois timers, depois I/O, depois setImmediate — bom saber ao agendar trabalho subsequente.

nodejs
// run once after a delay (ms)
const t = setTimeout(() => console.log('hi'), 1000);

// run repeatedly every interval
const i = setInterval(() => console.log('tick'), 2000);

// run right after the current event loop turn
setImmediate(() => console.log('immediate'));

// run before the next event loop turn (microtask)
queueMicrotask(() => console.log('microtask'));

// order inside one loop:
// microtasks -> timers -> I/O -> check (setImmediate)

Limpando Timers e ref

Cada timer tem uma função clear correspondente. unref() marca um timer como 'não mantenha o processo vivo' — se só restarem timers unref'd, o Node sai (prático para limpeza periódica que não deve prender o processo). ref() reverte. Argumentos extras depois do atraso são repassados ao callback, evitando uma arrow function extra.

nodejs
const t = setTimeout(() => {}, 1000);
clearTimeout(t);     // cancel

const i = setInterval(() => {}, 1000);
clearInterval(i);

const imm = setImmediate(() => {});
clearImmediate(imm);

// keep the event loop alive?
// timers do by default; unref() lets the process exit if
// only this timer is pending
const timer = setInterval(() => {}, 1000);
timer.unref();       // won't keep Node alive
timer.ref();         // keep alive again

// pass args to the callback
setTimeout((a, b) => console.log(a, b), 500, 'x', 'y');

util.inspect e format

util.format constrói strings com placeholders estilo printf (%s %d %j %o %O %%). util.inspect renderiza qualquer objeto — passe { depth: null, colors: true } para um despejo completo e colorido, útil em logs. util.deprecate embrulha uma função para emitir um DeprecationWarning (revelado com --trace-deprecation) quando chamada.

nodejs
const util = require('util');

// format like printf
util.format('%s:%d', 'port', 3000);   // 'port:3000'
util.format('%j', { a: 1 });           // JSON

// deep inspect an object (what console.dir uses)
util.inspect(obj, { depth: null, colors: true, compact: false });

// pretty-print a function (its source)
util.inspect(function f() { return 1; });

// deprecate an API with a warning
const oldFn = util.deprecate(
  () => doThingOldWay(),
  'oldFn() is deprecated, use newFn() instead'
);

util.promisify

util.promisify embrulha uma função de callback error-first numa que retorna Promise — a ponte de APIs de callback legadas para async/await. Muitos módulos centrais agora trazem versões nativas de promise (fs/promises), que são preferíveis, mas o promisify ainda resgata APIs de callback de terceiros. Uma função pode definir [util.promisify.custom] para controlar a conversão.

nodejs
const util = require('util');
const fs = require('fs');

// turn an error-first callback fn into a promise fn
const readFile = util.promisify(fs.readFile);
const text = await readFile('data.txt', 'utf8');

// works on custom functions too
function delay(ms, cb) { setTimeout(() => cb(null, ms), ms); }
const delayP = util.promisify(delay);
await delayP(100);

// custom promisify symbol (controls the promise behavior)
// const { promisify } = util;
// obj[util.promisify.custom] = () => Promise.resolve(42);

// many core modules ship promise versions directly:
// require('fs/promises'), require('dns/promises')

Tipos do util e callbackify

util.types oferece checagens de tipo confiáveis (isPromise, isAsyncFunction, isRegExp, isMap) que sobrevivem melhor a casos extremos de cross-realm e subclasses que instanceof. util.callbackify reverte o promisify — útil quando você precisa expor uma função baseada em promise a uma API de callback. util.MIMEType (Node 19+) analisa e manipula tipos MIME.

nodejs
const util = require('util');

// type checks
util.isPromise(Promise.resolve());    // true
util.isFunction(() => {});            // true
util.types.isMap(new Map());          // true
util.types.isAsyncFunction(async () => {}); // true
util.types.isRegExp(/x/);             // true

// reverse of promisify: promise -> error-first callback
const readFileCb = util.callbackify(require('fs/promises').readFile);
readFileCb('x.txt', 'utf8', (err, data) => {
  if (err) console.error(err);
  else console.log(data);
});

// MIME type utilities (Node 19+)
util.MIMEType.parse('text/html; charset=utf-8');

nextTick vs setImmediate

process.nextTick roda logo depois da operação síncrona atual, ANTES do I/O — então chamar nextTick recursivamente pode deixar o I/O faminto indefinidamente (o loop nunca avança). setImmediate roda depois do I/O, na fase 'check'. Para ceder ao event loop e deixar o I/O pendente assentar, prefira setImmediate; reserve nextTick para limpeza que precisa acontecer antes de qualquer callback de I/O.

nodejs
// process.nextTick: runs BEFORE I/O, after the current op
process.nextTick(() => console.log('tick'));

// setImmediate: runs AFTER I/O events, in the 'check' phase
setImmediate(() => console.log('immediate'));

// setTimeout(0): runs in the timers phase, after nextTick
setTimeout(() => console.log('timeout'), 0);

// typical order in one loop turn:
// 1. current sync code
// 2. nextTick callbacks  (can starve I/O!)
// 3. timers
// 4. I/O callbacks
// 5. setImmediate

// prefer setImmediate to yield to I/O; use nextTick for
// immediate post-sync cleanup

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.