nodejs-docs

API Node.js (nodejs.org)

Condensa a documentação da API Node.js no que um modelo tende a errar: padrões inseguros, armadilhas, depreciações. Cada afirmação termina com sua página nodejs.org.

Versão coberta

A documentação lida é v26.13.0. Muitos projetos executam a linha LTS v24, portanto as referências marcam o que é mais novo: "adicionado em v25.x" ou "adicionado em v26.x" significa ausente na v24, a menos que uma versão de backport seja fornecida. https://nodejs.org/docs/latest/api/

Antes de confiar em uma funcionalidade sinalizada, verifique process.version ou faça detecção de funcionalidade (process.features.typescript, process.features.require_module). https://nodejs.org/docs/latest/api/process.html

Leia as regras abaixo e depois abra o arquivo de referência correspondente.

Regras de maior valor

• Nunca chame access(), exists() ou stat() antes de abrir um arquivo: abra diretamente e trate ENOENT / EEXIST (flag 'wx' para criação exclusiva). https://nodejs.org/docs/latest/api/fs.html#fsaccesspath-mode-callback
• Feche explicitamente todo FileHandle, de preferência com await using. Um FileHandle deixado para o GC lança erro. https://nodejs.org/docs/latest/api/deprecations.html#DEP0137
• Componha streams com pipeline(), não com cadeias .pipe(), e respeite write() retornando false. https://nodejs.org/docs/latest/api/stream.html#readablepipedestination-options
• Adicione um listener 'error' a todo emitter, stream, socket, requisição e processo filho: um 'error' não tratado quebra o processo. https://nodejs.org/docs/latest/api/events.html#error-events
• Faça branch em err.code, nunca em err.message. https://nodejs.org/docs/latest/api/errors.html#errorcode
• Defina process.exitCode em vez de chamar process.exit(), que pode truncar a saída padrão. https://nodejs.org/docs/latest/api/process.html#processexitcode
• Nunca retome o trabalho após 'uncaughtException': limpe sincronamente e saia. https://nodejs.org/docs/latest/api/process.html#warning-using-uncaughtexception-correctly
• Prefira queueMicrotask() ao legado process.nextTick(). https://nodejs.org/docs/latest/api/process.html#when-to-use-queuemicrotask-vs-processnexttick
• Use execFile()/spawn() sem shell. Passar args com shell: true não os escapa. https://nodejs.org/docs/latest/api/deprecations.html#DEP0190
• Consuma todo corpo de resposta do cliente HTTP (res.resume() no mínimo), anexe req.on('error') e lembre-se de que timeout não aborta: chame destroy(). https://nodejs.org/docs/latest/api/http.html#class-httpclientrequest
• Mantenha headersTimeout diferente de zero em servidores sem proxy reverso. https://nodejs.org/docs/latest/api/http.html#serverheaderstimeout
• Use a URL do WHATWG. url.parse() está depreciada e nenhum CVE é emitido para ela. https://nodejs.org/docs/latest/api/deprecations.html#DEP0169
• path.isAbsolute() não impede travessia de caminho, e path.normalize() é lexical e pode alterar como o sistema resolve o caminho: resolva, então verifique se o resultado permanece dentro da raiz. https://nodejs.org/docs/latest/api/path.html#pathisabsolutepath
• Use Buffer.alloc() por padrão, Buffer.subarray() para visualizações, e nunca new Buffer(). https://nodejs.org/docs/latest/api/deprecations.html#DEP0005
• Compare segredos com crypto.timingSafeEqual() em buffers de igual comprimento. https://nodejs.org/docs/latest/api/crypto.html#cryptotimingsafeequala-b
• Defina maxOutputLength ao descomprimir dados não confiáveis com zlib (padrão buffer.kMaxLength). https://nodejs.org/docs/latest/api/zlib.html#class-options
• Defina "type" em package.json e coloque "default" por último nas condições de "exports". https://nodejs.org/docs/latest/api/packages.html#determining-module-system
• require() de ESM funciona para grafos síncronos. await de nível superior em qualquer lugar do grafo lança ERR_REQUIRE_ASYNC_MODULE. https://nodejs.org/docs/latest/api/modules.html#loading-ecmascript-modules-using-require
• Type stripping executa .ts sem verificação de tipos: sem enum, extensões .ts explícitas, import type e sem tsconfig paths. É estável desde v25.2.0 (backportado para v24.12.0), detecte com process.features.typescript. https://nodejs.org/docs/latest/api/typescript.html#typescript-features , https://nodejs.org/docs/latest/api/typescript.html#type-stripping
• Registre hooks de módulo com module.registerHooks(). module.register() está depreciada na v26. https://nodejs.org/docs/latest/api/deprecations.html#DEP0205
• Prefira AsyncLocalStorage a async_hooks.createHook(). https://nodejs.org/docs/latest/api/async_hooks.html
• Use await t.test() para subtests em node:test. https://nodejs.org/docs/latest/api/test.html#subtests
• node:vm e WASI não são sandboxes, e o Modelo de Permissões não é uma forma segura de executar código não confiável: nunca os use para isso. https://nodejs.org/docs/latest/api/permissions.html#process-based-permissions
• Descarte servidores, streams e processos filhos com using / await using, não com um AbortSignal. Mantenha signals para cancelamento e timeouts. https://nodejs.org/docs/latest/api/deprecations.html#DEP0209
• dns.lookup() é getaddrinfo no threadpool, não uma consulta DNS. https://nodejs.org/docs/latest/api/dns.html#implementation-considerations
• Dimensione pools com os.availableParallelism(). https://nodejs.org/docs/latest/api/os.html#osavailableparallelism
• node:sqlite: vincule parâmetros, nunca interpole em SQL. https://nodejs.org/docs/latest/api/sqlite.html#binding-parameters
• Execute CI com --pending-deprecation para expor depreciações. https://nodejs.org/docs/latest/api/deprecations.html

Arquivos de referência

Arquivo	Leia para
references/fs.md	TOCTOU, FileHandle, readFile/writeFile, rm, glob, fs.watch
references/path-and-url.md	path, travessia, URLs file:, URL do WHATWG, querystring
references/crypto.md	KeyObject, timingSafeEqual, hashing, pbkdf2, scrypt, algoritmos fracos
references/ciphers-and-webcrypto.md	Tags AEAD, GCM, key wrap, subtle, formatos de chave
references/streams.md	pipeline, backpressure, highWaterMark, finished, implementando streams
references/web-streams-and-stream-iter.md	Web Streams, node:stream/iter
references/buffer.md	alloc versus allocUnsafe, codificações, Blob
references/zlib.md	bombas de descompressão, flush, Zstd
references/http-client.md	http.request, agents, keep-alive, proxy
references/http-server.md	timeouts, desligamento gracioso, servidores HTTPS
references/net-dns-dgram.md	TCP, BlockList, dns.lookup versus resolve, UDP
references/tls.md	SNI, cifras, armazenamento CA, retomada de sessão
references/http2.md	servidor seguro, allowHTTP1, hardening
references/process.md	códigos de saída, signals, uncaughtException, rejeições
references/cli-and-env-files.md	NODE_OPTIONS, --env-file, --watch
references/permissions.md	--permission, lacunas conhecidas
references/errors.md	error.code, cause, códigos de erro
references/events-and-timers.md	captureRejections, events.once, EventTarget, timers
references/async-context-and-diagnostics-channel.md	AsyncLocalStorage, diagnostics_channel
references/util-and-console.md	util, Console
references/os-tty-readline-repl.md	os, tty, readline, REPL
references/test-runner.md	subtests, isolamento, cobertura, reporters, mocks
references/assert-and-bench.md	node:assert/strict, igualdade profunda, node:bench
references/esm-and-commonjs.md	"type", importações JSON, import.meta, require(esm)
references/packages.md	"exports", "imports", condições, pacotes duais
references/typescript-and-module-hooks.md	type stripping, registerHooks, findPackageJSON
references/globals.md	fetch, AbortSignal, globais
references/child-process.md	execFile versus exec, maxBuffer, IPC
references/worker-threads-and-cluster.md	pools, listas de transferência, cluster
references/vm-wasi-vfs.md	vm, WASI, node:vfs
references/performance-and-profiling.md	perf_hooks, snapshots de heap
references/debugging-and-reports.md	inspetor, relatórios de diagnóstico
references/sqlite.md	Database, padrões, vinculação, conversão de tipos
references/sea-and-native.md	SEA, regras Node-API, node:ffi
references/deprecations.md	códigos DEP, APIs removidas, codemods

As páginas lidas, versão e data de obtenção estão listadas em SOURCES.md.