Node.js
Recorrido por APIs avanzadas de Node.js y criterios para adoptarlas de forma progresiva según estabilidad, compatibilidad, soporte del runtime y necesidades reales.
Node.js incorpora APIs web, diagnóstico, almacenamiento, permisos y distribución que evolucionan a ritmos distintos. Antes de adoptar una capacidad reciente, comprueba cuatro cosas: estabilidad en la versión desplegada, requisitos mínimos, límites operativos y beneficio real. Una API presente no es automáticamente una dependencia adecuada para producción.
problema concreto
→ API disponible en la versión objetivo
→ comprobar estabilidad y limitaciones
→ encapsular detrás de una frontera
→ tests + métricas + fallback
→ rollout progresivoLa documentación de la versión instalada es la fuente de verdad. Una API puede ser estable en Node 26 y todavía experimental o release candidate en Node 24.
| Estado | Interpretación |
|---|---|
| Stable | Compatibilidad prioritaria; puede formar parte del contrato normal. |
| Release candidate | No se esperan grandes cambios, pero aún puede cambiar antes de estabilizarse. |
| Active development | API experimental cercana a viabilidad mínima; evita depender de ella sin aislamiento. |
| Experimental | No está protegida plenamente por semver y puede cambiar o desaparecer. |
| Legacy | Sigue soportada, pero existen alternativas preferidas y recibe menos evolución. |
No uses únicamente el número global del módulo: algunas funciones dentro de un módulo pueden tener estabilidad diferente.
Node moderno expone APIs compatibles con la plataforma web:
fetch.Request y Response.Headers.FormData.Blob y File.URL y URLSearchParams.AbortController y AbortSignal.WebSocket.globalThis.crypto.Aportan portabilidad entre navegador, runtimes serverless y Node, pero el entorno sigue siendo distinto:
same interface
≠ same network stack
≠ same filesystem
≠ same lifecycle
≠ same security contextconst signal = AbortSignal.timeout(5_000);
const response = await fetch("https://api.example.com/orders", { signal });
if (!response.ok) {
throw new Error(`Upstream returned ${response.status}`);
}Recuerda:
404 o 500.APIs útiles:
AbortSignal.timeout(5_000);
AbortSignal.any([requestSignal, shutdownSignal]);Un timeout local no basta si las capas internas ignoran la señal. Propágala hasta DB, fetch, timers, pipeline o trabajo propio cuando la API lo permita.
La implementación global compatible con navegador es estable en líneas modernas:
const socket = new WebSocket("wss://example.com/events");No incluye automáticamente:
Para un servidor WebSocket todavía puedes necesitar una librería o infraestructura específica; la API global documentada representa principalmente el cliente.
ReadableStream, WritableStream y TransformStream son estables en líneas LTS modernas. Node Streams continúan siendo fundamentales para fs, http y ecosistema.
import { Readable } from "node:stream";
const webStream = Readable.toWeb(nodeReadable);
const nodeStream = Readable.fromWeb(webReadable);Prueba:
No conviertas repetidamente entre modelos dentro de una ruta caliente sin medir.
globalThis.crypto.subtle facilita código portable. node:crypto ofrece además streams, utilidades de certificados, password derivation y capacidades específicas.
Elige según:
Ninguna de las dos APIs justifica inventar protocolos criptográficos.
El Permission Model es estable en las líneas soportadas modernas y se habilita con:
node --permission \
--allow-fs-read=./config \
--allow-fs-write=./tmp \
app.jsRestringe capacidades como:
Runtime API:
if (!process.permission.has("fs.read", configPath)) {
throw new Error("Missing config permission");
}Funciona como un seat belt para código confiable: evita que una aplicación o dependencia acceda accidentalmente a recursos no concedidos.
No es un sandbox contra código malicioso. La política oficial de Node asume que el código ejecutado es confiable y documenta formas y limitaciones que pueden eludir la expectativa de aislamiento.
Mantén además:
No promociones el Permission Model como defensa absoluta ante paquetes maliciosos.
node:sqlite permite trabajar con SQLite sin dependencia externa:
import { DatabaseSync } from "node:sqlite";
const database = new DatabaseSync(":memory:");
database.exec(`
CREATE TABLE notes (
id INTEGER PRIMARY KEY,
title TEXT NOT NULL
) STRICT
`);
const insert = database.prepare(
"INSERT INTO notes (title) VALUES (?)"
);
insert.run("Event loop");En la línea Node 24 actual se encuentra como release candidate, no como API completamente estable. Verifica el estado exacto antes de convertirla en contrato de una librería.
DatabaseSync bloquea el hilo durante las operaciones.Para requests concurrentes, mide latencia y considera worker dedicado, cola o una base cliente-servidor cuando la carga lo justifique.
La compile cache persiste bytecode/código de V8 para reducir compilación en arranques posteriores:
import { enableCompileCache } from "node:module";
enableCompileCache();También puede activarse mediante:
NODE_COMPILE_CACHE=/tmp/node-compile-cache node app.jsCaracterísticas:
Por eso, desactívala durante coverage cuando necesites precisión:
NODE_DISABLE_COMPILE_CACHE=1 node --test --experimental-test-coverageNo trates una cache de compilación como artefacto durable entre versiones o arquitecturas sin probarlo.
node:module permite hooks de resolución y carga. Pueden servir para:
Pero alteran una de las partes más sensibles del runtime:
specifier
→ resolve hook
→ load hook
→ module evaluationRiesgos:
Prefiere exports, imports y loaders estándar antes de crear resolución personalizada.
SEA permite distribuir una aplicación Node dentro de un ejecutable. Es útil para CLIs o entornos donde no quieres instalar Node por separado.
Debes comprobar:
No es “compilar JavaScript a máquina” en el sentido tradicional: empaqueta runtime y aplicación bajo un proceso de construcción específico.
Snapshots V8 pueden precargar estado para mejorar startup. Son avanzados porque el estado capturado debe ser seguro y reproducible.
Evita capturar:
Mide cold start real antes de introducir un pipeline de snapshots.
node:vm ejecuta código en contextos diferentes, pero no constituye una frontera de seguridad para código hostil.
separate context
≠ separate process
≠ resource isolation
≠ secure sandboxPara plugins no confiables utiliza aislamiento diseñado para ello: proceso separado, container, límites de CPU/memoria y protocolo mínimo.
Node-API permite integrar C/C++ con estabilidad ABI mejor que usar internals de V8 directamente.
Un addon puede:
Úsalo solo cuando el rendimiento o acceso nativo justifique el coste. Prefiere prebuilds firmados, Node-API y fallback cuando sea posible.
Wasm aporta un formato portable para código compilado. No garantiza:
Mide el coste de copiar datos entre JavaScript y Wasm. Para trabajo CPU-bound grande, un worker puede seguir siendo necesario para no bloquear el hilo principal.
El inspector permite:
Nunca lo expongas a internet sin una frontera fuerte. Quien accede al inspector puede controlar el proceso y leer memoria/secrets.
node --inspect=127.0.0.1:9229 app.jsPrefiere loopback, túnel autenticado y ventanas temporales de diagnóstico.
Una API nueva no debe entrar solo porque elimina una dependencia. Evalúa:
| Capacidad | Uso recomendado | Precaución principal |
|---|---|---|
| Fetch/WebSocket | Clientes web portables | Timeout, SSRF, pooling, reconexión |
| Web Streams | Interop con APIs web | Conversión y backpressure |
| Permission Model | Defensa adicional | No es sandbox |
| `node:sqlite` | Persistencia local | RC y operaciones síncronas |
| Compile cache | Startup repetido | Versionado y coverage |
| SEA | Distribuir CLIs | Build y plataforma |
| VM | Contextos controlados | No ejecutar código hostil |
| Wasm/addons | Trabajo especializado | Memoria, bloqueo y supply chain |
Para cada capacidad reciente prueba:
Una LTS anterior puede no tener la API o tener otro estado.
No protege frente a código malicioso.
Puede bloquear requests concurrentes.
Puede reducir precisión.
El aislamiento es insuficiente.
Entrega control del proceso.
La API nativa puede no incluir retry, pooling, server mode o ergonomía equivalente.
node:sqlite sigue siendo release candidate en la línea LTS revisada.DatabaseSync en un servidor?TypeScript nativo en Node.js diferencia ejecución directa, type stripping, type checking y compilación.