nodejs-docs

API de Node.js (nodejs.org)

Condensa la documentación de la API de Node.js en lo que un modelo tiende a equivocarse: valores predeterminados inseguros, errores comunes, funciones obsoletas. Cada afirmación termina con su página de nodejs.org.

Versión cubierta

La documentación leída es v26.13.0. Muchos proyectos ejecutan la línea LTS v24, por lo que las referencias indican qué es más nuevo: "agregado en v25.x" o "agregado en v26.x" significa que falta en v24 a menos que se indique una versión backportada. https://nodejs.org/docs/latest/api/

Antes de confiar en una función marcada, verifique process.version o detecte la función (process.features.typescript, process.features.require_module). https://nodejs.org/docs/latest/api/process.html

Lea las reglas a continuación y luego abra el archivo de referencia correspondiente.

Reglas de mayor valor

• Nunca llame a access(), exists() o stat() antes de abrir un archivo: ábralo directamente y maneje ENOENT / EEXIST (bandera 'wx' para creación exclusiva). https://nodejs.org/docs/latest/api/fs.html#fsaccesspath-mode-callback
• Cierre cada FileHandle explícitamente, idealmente con await using. Un FileHandle dejado al recolector de basura lanza una excepción. https://nodejs.org/docs/latest/api/deprecations.html#DEP0137
• Componga streams con pipeline(), no con cadenas de .pipe(), y respete que write() devuelva false. https://nodejs.org/docs/latest/api/stream.html#readablepipedestination-options
• Agregue un listener 'error' a cada emisor, stream, socket, solicitud y proceso hijo: un 'error' no manejado bloquea el proceso. https://nodejs.org/docs/latest/api/events.html#error-events
• Ramifique en err.code, nunca en err.message. https://nodejs.org/docs/latest/api/errors.html#errorcode
• Establezca process.exitCode en lugar de llamar a process.exit(), que puede truncar la salida estándar. https://nodejs.org/docs/latest/api/process.html#processexitcode
• Nunca reanude el trabajo después de 'uncaughtException': limpie de forma síncrona y salga. https://nodejs.org/docs/latest/api/process.html#warning-using-uncaughtexception-correctly
• Prefiera queueMicrotask() al antiguo process.nextTick(). https://nodejs.org/docs/latest/api/process.html#when-to-use-queuemicrotask-vs-processnexttick
• Use execFile()/spawn() sin un shell. Pasar args con shell: true no los escapa. https://nodejs.org/docs/latest/api/deprecations.html#DEP0190
• Consuma cada cuerpo de respuesta del cliente HTTP (res.resume() como mínimo), adjunte req.on('error') y recuerde que timeout no aborta: llame a destroy(). https://nodejs.org/docs/latest/api/http.html#class-httpclientrequest
• Mantenga headersTimeout distinto de cero en servidores sin proxy inverso. https://nodejs.org/docs/latest/api/http.html#serverheaderstimeout
• Use la URL WHATWG. url.parse() está obsoleto y no se emiten CVEs por ello. https://nodejs.org/docs/latest/api/deprecations.html#DEP0169
• path.isAbsolute() no detiene la travesía de rutas, y path.normalize() es léxico y puede cambiar cómo el sistema resuelve la ruta: resuelva y luego verifique que el resultado permanezca dentro de la raíz. https://nodejs.org/docs/latest/api/path.html#pathisabsolutepath
• Use Buffer.alloc() por defecto, Buffer.subarray() para vistas, y nunca new Buffer(). https://nodejs.org/docs/latest/api/deprecations.html#DEP0005
• Compare secretos con crypto.timingSafeEqual() en buffers de igual longitud. https://nodejs.org/docs/latest/api/crypto.html#cryptotimingsafeequala-b
• Establezca maxOutputLength al descomprimir datos no confiables con zlib (por defecto buffer.kMaxLength). https://nodejs.org/docs/latest/api/zlib.html#class-options
• Establezca "type" en package.json, y ponga "default" al final en las condiciones de "exports". https://nodejs.org/docs/latest/api/packages.html#determining-module-system
• require() de ESM funciona para gráficos síncronos. await de nivel superior en cualquier lugar del gráfico lanza ERR_REQUIRE_ASYNC_MODULE. https://nodejs.org/docs/latest/api/modules.html#loading-ecmascript-modules-using-require
• La eliminación de tipos (type stripping) ejecuta .ts sin verificación de tipos: no use enum, extensiones .ts explícitas, import type, y no use paths de tsconfig. Es estable desde v25.2.0 (backportado a v24.12.0), detecte con 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 con module.registerHooks(). module.register() está obsoleto en v26. https://nodejs.org/docs/latest/api/deprecations.html#DEP0205
• Prefiera AsyncLocalStorage a async_hooks.createHook(). https://nodejs.org/docs/latest/api/async_hooks.html
• Use await t.test() para subpruebas en node:test. https://nodejs.org/docs/latest/api/test.html#subtests
• node:vm y WASI no son entornos aislados (sandboxes), y el Modelo de Permisos no es una forma segura de ejecutar código no confiable: nunca los use para eso. https://nodejs.org/docs/latest/api/permissions.html#process-based-permissions
• Elimine servidores, streams y procesos hijo con using / await using, no con un AbortSignal. Reserve las señales para cancelación y tiempos de espera. https://nodejs.org/docs/latest/api/deprecations.html#DEP0209
• dns.lookup() es getaddrinfo en el grupo de subprocesos (threadpool), no una consulta DNS. https://nodejs.org/docs/latest/api/dns.html#implementation-considerations
• Dimensione los pools con os.availableParallelism(). https://nodejs.org/docs/latest/api/os.html#osavailableparallelism
• node:sqlite: vincule parámetros, nunca interpole en SQL. https://nodejs.org/docs/latest/api/sqlite.html#binding-parameters
• Ejecute CI con --pending-deprecation para detectar funciones obsoletas. https://nodejs.org/docs/latest/api/deprecations.html

Archivos de referencia

Archivo	Léalo para
references/fs.md	TOCTOU, FileHandle, readFile/writeFile, rm, glob, fs.watch
references/path-and-url.md	path, travesía, URLs file:, URL WHATWG, querystring
references/crypto.md	KeyObject, timingSafeEqual, hashing, pbkdf2, scrypt, algoritmos débiles
references/ciphers-and-webcrypto.md	Etiquetas AEAD, GCM, key wrap, subtle, formatos de clave
references/streams.md	pipeline, contrapresión (backpressure), highWaterMark, finished, implementación de streams
references/web-streams-and-stream-iter.md	Web Streams, node:stream/iter
references/buffer.md	alloc versus allocUnsafe, codificaciones, Blob
references/zlib.md	Bombas de descompresión, flush, Zstd
references/http-client.md	http.request, agentes, keep-alive, proxy
references/http-server.md	Tiempos de espera, apagado graceful, servidores HTTPS
references/net-dns-dgram.md	TCP, BlockList, dns.lookup versus resolve, UDP
references/tls.md	SNI, cifrados, almacén de CA, reanudación de sesión
references/http2.md	Servidor seguro, allowHTTP1, endurecimiento
references/process.md	Códigos de salida, señales, uncaughtException, rechazos
references/cli-and-env-files.md	NODE_OPTIONS, --env-file, --watch
references/permissions.md	--permission, brechas conocidas
references/errors.md	error.code, cause, códigos de error
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	Subpruebas, aislamiento, cobertura, reporteros, mocks
references/assert-and-bench.md	node:assert/strict, igualdad profunda, node:bench
references/esm-and-commonjs.md	"type", importaciones JSON, import.meta, require(esm)
references/packages.md	"exports", "imports", condiciones, paquetes duales
references/typescript-and-module-hooks.md	Eliminación de tipos (type stripping), registerHooks, findPackageJSON
references/globals.md	fetch, AbortSignal, globales
references/child-process.md	execFile versus exec, maxBuffer, IPC
references/worker-threads-and-cluster.md	Pools, listas de transferencia, cluster
references/vm-wasi-vfs.md	vm, WASI, node:vfs
references/performance-and-profiling.md	perf_hooks, instantáneas de heap
references/debugging-and-reports.md	Inspector, informes de diagnóstico
references/sqlite.md	Database, valores predeterminados, vinculación, conversión de tipos
references/sea-and-native.md	SEA, reglas de Node-API, node:ffi
references/deprecations.md	Códigos DEP, APIs eliminadas, codemods

Las páginas leídas, la versión y la fecha de recuperación se enumeran en SOURCES.md.