Skip to content

Node.js Hoja de referencia

Runtime de JavaScript construido sobre el motor V8 de Chrome para desarrollo del lado del servidor.

01

Primeros pasos

REPL y ejecución de scripts

El REPL (Read-Eval-Print Loop) es un shell interactivo para experimentar con código de Node.js. Usa node --watch para autorreinicio en desarrollo. Los módulos ES exigen type:module en package.json o la extensión .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

Versión y flags del runtime

node --version imprime la versión del runtime. --trace-warnings muestra stack traces para las advertencias de runtime. NODE_OPTIONS es una única variable de entorno que guarda flags de CLI, práctica dentro de contenedores o scripts de npm. --inspect abre el depurador de 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 inicio de proyecto

npm init crea package.json. El campo "type" decide el sistema de módulos por defecto: "module" habilita la sintaxis de módulos ES en archivos .js, "commonjs" (por defecto) conserva require/module.exports. "main" es el punto de entrada cuando el paquete es 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 módulos ES

Node soporta dos sistemas de módulos. CommonJS (require/module.exports) es sincrónico y el valor histórico por defecto. Los módulos ES (import/export) son el estándar moderno. La extensión del archivo (.mjs/.cjs) o el campo "type" de package.json deciden qué parser se usa para los archivos .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 globales

Node ofrece globales como process, console, Buffer y los temporizadores sin imports. __dirname y __filename son exclusivos de CommonJS — en módulos ES usa import.meta.url en su lugar. global es el objeto de ámbito raíz (como window en los 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 ejecutables (shebang)

Una línea shebang (#!/usr/bin/env node) permite que un archivo corra como comando independiente en Unix. Tras chmod +x, ejecuta ./cli.js directamente. El campo "bin" de package.json mapea un nombre de comando a un script, usado por las herramientas CLI publicadas en npm para que la instalación global exponga el 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

require y exports de CommonJS

require() carga sincrónicamente un módulo CommonJS y devuelve su module.exports. require resuelve rutas relativas (./, ../), integrados (fs) y node_modules. Asigna siempre a module.exports (no a exports) al reemplazar toda la exportación, porque exports es solo un alias de 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

import/export de módulos ES

Los módulos ES usan import/export estático — los enlaces son vivos y se elevan. La exportación por defecto se importa con cualquier nombre (sin llaves); las exportaciones con nombre deben usar llaves con nombres coincidentes. import * as crea un objeto de espacio de nombres. ESM es asíncrono por diseño y el estándar 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() es un import dinámico y asíncrono utilizable tanto en CJS como en ESM. Devuelve una Promise que resuelve al espacio de nombres del módulo, habilitando la carga perezosa y los imports condicionales — genial para reducir el tiempo de arranque o cargar características opcionales. Úsalo también para dividir código en servidores.

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 integrados

Node trae docenas de módulos integrados — sin npm install. La mayoría exponen APIs de callback; muchos también ofrecen variantes de promesa bajo la ruta 'module/promises' (fs/promises, dns/promises, stream/promises). require('module') (sin ./) resuelve primero a los integrados, luego a 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

Caché de módulos y dependencias circulares

require() cachea los módulos por ruta resuelta, así que el mismo código de módulo corre una vez y las exportaciones se reutilizan. Las dependencias circulares funcionan pero el módulo cargado primero ve un objeto de exports incompleto (parcial) del segundo — diseña a su alrededor. delete require.cache para hot-reload durante el desarrollo.

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 y __filename son globales exclusivos de CommonJS que dan la ruta actual de carpeta/archivo. Los módulos ES no tienen esos globales — derívalos de import.meta.url vía fileURLToPath. import.meta.url es la URL file:// del módulo actual y el reemplazo 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 y pnpm

npm init y package.json

npm init andamia un package.json. -y salta las preguntas con los valores por defecto. npm set guarda la configuración en ~/.npmrc para futuros inits. Los paquetes con ámbito (@org/nombre) son útiles para organizaciones y para evitar colisiones de nombre en el 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

Instalar dependencias

npm install (sin argumentos) instala todas las dependencias listadas. Con un nombre lo añade a package.json. --save-dev lo pone en devDependencies (herramientas de test/build, no distribuidas). ^ permite actualizaciones de minor+patch, ~ solo de patch. -g instala herramientas 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 de npm

Los scripts en package.json corren vía npm run <nombre>. start y test son especiales (npm start / npm test). Los hooks pre/post (pretest, postbuild) corren automáticamente. Usa -- para reenviar argumentos al comando subyacente. pnpm te permite omitir la palabra "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 y pnpm dlx

npx ejecuta un binario de un paquete sin instalación global — lo descarga, lo ejecuta y lo descarta. Perfecto para andamios (create-vite) y para correr herramientas locales de node_modules/.bin. --yes salta la confirmación de instalación. pnpm dlx es el homólogo en 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

Versionado y lockfiles

SemVer: MAJOR para cambios que rompen compatibilidad, MINOR para características, PATCH para correcciones. ^ (acento circunflejo) es el valor por defecto de npm y permite actualizaciones de minor+patch; ~ (tilde) solo patch. Los lockfiles (package-lock.json) congelan el árbol de dependencias completo para instalaciones reproducibles — usa npm ci en CI por velocidad y seguridad.

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

Publicación y ciclo de vida

npm publish sube tu paquete al registro. npm version sube la versión, crea un git tag y hace commit. Los hooks del ciclo de vida (prepublishOnly, postpublish) automatizan build/test al publicar. Unpublish solo se permite dentro de las 72 horas — prefiere npm deprecate para versiones antiguas.

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 archivos (fs)

Leer archivos

fs ofrece APIs sincrónica (readFileSync), de callback (readFile) y de promesa (fs/promises readFile). Las llamadas sincrónicas bloquean el event loop — evítalas en servidores. fs/promises es la elección moderna para async/await. Sin una codificación, readFile devuelve un 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;
}

Escribir archivos

writeFile reemplaza el archivo completo por defecto. La opción flag cambia el comportamiento: 'a' añade, 'wx' falla (EEXIST) si el archivo ya existe — útil para creación atómica de archivos. El JSON debe serializarse antes de escribirlo. Las escrituras sincrónicas bloquean; prefiere 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

Directorios

mkdir con { recursive: true } imita a mkdir -p. readdir lista las entradas; { withFileTypes: true } devuelve objetos Dirent cuyos isDirectory()/isFile() evitan llamadas stat extra. fsp.rm con recursive+force reemplaza a rmdir para directorios no vacíos (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

Estadísticas y metadatos de archivos

stat() devuelve un objeto Stats con size, mtime y helpers de tipo. No uses fs.exists (obsoleto); usa access() en un try/catch para comprobaciones de existencia sin carreras — aunque abrir el archivo directamente es más seguro. fsWatch emite eventos de cambio pero puede 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+) proporciona versiones basadas en promesas de cada función de fs, ideales para async/await. opendir() devuelve un iterador asíncrono para recorrer directorios con eficiencia de memoria. Combínalo con path.join para rutas portables. Todas las funciones lanzan ante error — envuélvelas en 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 añade contenido al final (crea el archivo si falta). rename es atómico en el mismo sistema de archivos y se usa para mover archivos. unlink elimina un archivo. copyFile copia contenido; fsp.cp (Node 16+) maneja directorios recursivamente. truncate redimensiona un archivo a la longitud dada.

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

Manejo de rutas

path.join y path.resolve

path.join concatena segmentos usando el separador de la plataforma y normaliza el resultado. path.resolve produce una ruta absoluta partiendo de process.cwd(); un segmento absoluto descarta los anteriores. Usa siempre path.join en lugar de concatenación de cadenas para que las rutas funcionen en Windows y 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 devuelve el directorio, basename el nombre del archivo (opcionalmente sin una extensión) y extname la última extensión (incluido el punto). Para extensiones de varias partes como .tar.gz solo se devuelve la .gz final. Son operaciones puras de cadena — sin acceso al sistema de archivos.

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 y format

path.parse divide una ruta en root, dir, base, name y ext. path.format los reensambla. path.relative calcula la ruta relativa necesaria para ir de un directorio a otro. Juntos hacen la manipulación de rutas declarativa en lugar de un troceado de cadenas delicado.

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'

Rutas multiplataforma

path.sep y path.delimiter difieren por sistema operativo. path.win32 y path.posix fuerzan un parser concreto sin importar el sistema anfitrión — práctico al procesar rutas de otra plataforma. Usa path.delimiter para dividir variables de env estilo PATH de forma portable en lugar de fijar ':' o ';' a fuego.

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 archivo y pathToFileURL

Los módulos ES se identifican por URLs file://. Usa url.pathToFileURL para convertir una ruta normal en una URL para import() dinámico, y url.fileURLToPath para ir en la dirección contraria. En ESM, import.meta.url ya es una URL de archivo — conviértela a ruta con 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 devuelve un servidor; el callback maneja cada petición. res.writeHead fija el código de estado y los headers, res.end envía el body y termina la respuesta. listen() empieza a aceptar conexiones en el puerto dado. Un proceso de Node maneja muchas peticiones concurrentes vía el 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, () => {});

Petición y respuesta

req expone method, url y headers; res te permite fijar statusCode/headers y luego write+end. res.end DEBE llamarse para terminar la respuesta. Para payloads grandes, transmite datos vía res.write o encadena un Readable a res con pipe para no almacenar la carga completa en memoria.

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

Enrutado y parseo de URL

Node no tiene router integrado — implementa uno con if/else sobre req.method y req.url, o usa el constructor URL para parsear pathname y searchParams. Para apps reales, recurre a Express o al router de un framework. El constructor URL necesita una base al parsear un 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);

Manejo de JSON y body POST

Los bodies de petición llegan como stream — debes recolectar los fragmentos antes de parsear. El patrón de iterador asíncrono (for await of req) es el enfoque moderno. Fja siempre Content-Type: application/json al responder con JSON. En producción, limita el tamaño del body para evitar el agotamiento de memoria.

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 y errores del servidor

El servidor es un EventEmitter. 'error' debe manejarse — EADDRINUSE significa que el puerto está ocupado. 'connection' se dispara por cada socket de cliente. Para un apagado elegante, escucha SIGTERM/SIGINT y llama a server.close() para que las peticiones en curso terminen antes de que el proceso salga.

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 y cliente HTTP

https.createServer requiere una clave privada y un certificado (por ejemplo, de Let's Encrypt). Para peticiones salientes, Node 18+ trae un fetch() global — prefierelo sobre la API de callback cruda http.get. fetch está basado en promesas y soporta async/await, headers y 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

Fundamentos de Express

Configuración de Express y Hello World

Express es el framework web de Node más popular. app.get registra un manejador de ruta; res.send envía una respuesta (detectando el Content-Type automáticamente). app.listen arranca el servidor. Express envuelve el módulo http de Node con enrutado, middleware y helpers de conveniencia.

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}`);
});

Enrutado y parámetros de ruta

Express empareja verbos HTTP (get/post/put/delete) con rutas. :id captura segmentos de URL en req.params; req.query guarda los valores de la query string. app.route te permite encadenar varios verbos para la misma ruta. Las rutas coinciden en orden de registro, así que define las específicas antes que las 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

Los middleware son funciones que corren durante el ciclo de la petición, recibiendo req, res y next. Llama a next() para continuar con el siguiente manejador. app.use monta middleware globalmente o sobre un prefijo de ruta. El middleware de manejo de errores tiene 4 argumentos (err primero) y debe registrarse al final.

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');
});

Datos de la petición

Express solo parsea bodies si montas el middleware adecuado: express.json() para JSON, express.urlencoded() para formularios, multer para subidas de archivos. req.params (segmentos de URL), req.query (query string) y req.body (payload parseado) son las tres fuentes principales de datos de la petición.

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

Servir archivos estáticos

express.static sirve archivos de un directorio. Móntalo varias veces para comportamiento de respaldo, o con un prefijo de ruta. Opciones como maxAge fijan headers de caché. Detecta automáticamente los tipos MIME y soporta peticiones de rango para vídeo/audio. Usa siempre rutas absolutas para evitar bugs dependientes del 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');
  }
}));

Manejo de errores y Router

Pasa un error a next(err) o lanza dentro de un manejador asíncrono para disparar el middleware de manejo de errores. Registra un manejador central de 4 argumentos al final. express.Router() modulariza las rutas en archivos separados — móntalos con app.use('/prefijo', router) para componer una API grande limpiamente.

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

Un stream Readable produce datos. En modo flujo, los eventos 'data' empujan fragmentos automáticamente; en modo pausa, llamas a read() explícitamente. Maneja siempre 'error' — los eventos de error no manejados tumban el proceso. highWaterMark controla el tamaño del búfer 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

Un stream Writable consume datos. write() devuelve false cuando el búfer interno está lleno — espera al evento 'drain' antes de escribir más para respetar la contrapresión. end() señala que no hay más datos; 'finish' se dispara tras vaciarse por completo. process.stdout es en sí un stream escribible.

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 y pipeline

pipe() reenvía un Readable a un Writable con contrapresión automática. stream.pipeline (prefiere la versión de promesas) encadena varios streams Y propaga correctamente los errores y limpia — .pipe() solo pierde recursos ante errores a mitad del stream. Prefiere siempre pipeline a las cadenas manuales 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

Un stream Transform lee entrada, la procesa y emite salida transformada — perfecto para parsear, comprimir o cifrar en un pipeline. Implementa transform(chunk, enc, cb) y opcionalmente flush(cb). objectMode te permite empujar objetos en lugar de Buffers. zlib y crypto aportan transformaciones listas para usar.

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 y contrapresión

Los streams alternan entre modo flujo y pausa vía pause()/resume(). La contrapresión significa que un consumidor lento le indica al productor que baje el ritmo — la iteración asíncrona (for await) lo maneja automáticamente esperando cada fragmento, el patrón moderno más limpio. Fja siempre una codificación para recibir cadenas en lugar 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

Hereda de Readable/Writable/Duplex e implementa _read/_write, o usa el más simple Readable.from() para datos que ya tienes. push(null) señala el fin del stream. Los streams Duplex son legibles Y escribibles de forma independiente (como los sockets TCP); Transform es un Duplex donde la salida deriva de la 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

Crear buffers

Buffer.alloc crea un buffer relleno de ceros (seguro). Buffer.allocUnsafe se salta el rellenado por velocidad pero puede filtrar memoria antigua — úsalo solo cuando vayas a sobrescribir cada byte. Buffer.from convierte cadenas/arrays/buffers. El constructor heredado 'new Buffer()' está obsoleto por motivos de seguridad.

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

Leer y escribir

Los buffers guardan bytes crudos. Usa las funciones de lectura/escritura con tamaños explícitos (UInt8/16/32) y endianness (BE/LE). Big-endian es el orden de bytes de red; little-endian es común en x86. toString(encoding, start, end) decodifica bytes a cadena. Pasa siempre un offset para no sobrescribir 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 y compare

Buffer.concat une un array de buffers (una pista opcional de longitud total mejora el rendimiento). equals/compare te permiten comparar secuencias de bytes; indexOf/includes hallan sub-buffers — útil en protocolos binarios. copy(target, targetStart, sourceStart, sourceEnd) copia una rebanada a otro 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

Codificaciones

Las codificaciones mapean entre cadenas y bytes. utf8 es la de por defecto para texto. base64/hex son comunes para binario-en-texto (data URLs, hashes, transporte). Buffer.byteLength da el tamaño en bytes (los caracteres multibyte cuentan más de un byte en utf8) — úsalo al dimensionar buffers, no 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 y TypedArrays

Buffer extiende Uint8Array, así que funciona donde lo hagan los TypedArrays. Buffer.from(arrayBuffer) comparte memoria (sin copia) — pero un Buffer puede rebanar un ArrayBuffer agrupado mayor, así que respeta siempre byteOffset/byteLength al crear vistas. Esto te permite mezclar APIs de Buffer con DataView para acceso 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 (o slice) devuelve una vista que comparte la memoria original — las mutaciones afectan a ambos. fill escribe un byte o una cadena repetida a lo largo del buffer. swap16/swap32 invierten el orden de bytes en el sitio para conversión de endianness. Los buffers son iterables, cediendo 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

Crear y emitir eventos

EventEmitter es el núcleo pub/sub de Node. emit(nombreEvento, ...args) dispara un evento; on() se suscribe. Muchas clases integradas (streams, servidor http) lo extienden. Los nombres de eventos son cadenas arbitrarias, aunque 'error' es especial. Los listeners se llaman sincrónicamente en orden 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 y removeListener

once() registra un listener que se autoelimina tras dispararse — genial para configuración única. Para quitar un listener debes conservar una referencia a la función exacta (las funciones flecha crean referencias nuevas cada vez). removeAllListeners limpia los listeners de un evento o de la totalidad. off es un alias de 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 error

Si se emite un evento 'error' y NO hay listener registrado, Node lanza y tumba el proceso. Adjunta siempre un manejador de error a los EventEmitters — especialmente a streams y servidores HTTP. captureRejections (Node 12+) enruta las promesas rechazadas de listeners asíncronos al 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 asíncronos

EventEmitter llama a los listeners sincrónicamente, así que la promesa de un listener asíncrono no se espera — emit() devuelve antes de que se resuelva. Usa once(ee, name) para esperar un solo evento como promesa. Habilita captureRejections para que un listener asíncrono rechazado dispare el evento 'error' en lugar de perderse en silencio.

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));

Nombrado de eventos y newListener

newListener y removeListener son eventos especiales que se emiten al añadir/quitar listeners — útiles para hooks o perfilar. setMaxListeners sube el umbral de detección de fugas (10 por defecto); la advertencia normalmente significa que olvidaste limpiar los listeners. Usa Symbols o constantes para los nombres de eventos para evitar errores tipográficos.

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

Procesos hijos

exec (shell, con búfer)

exec() corre un comando vía un shell y guarda stdout/stderr en búfer — lo mejor para comandos cortos donde quieres toda la salida de una vez. Genera un shell, así que expande globs y pipes. NUNCA interpolés entrada de usuario en la cadena de comando — es una vulnerabilidad de inyección de comandos; usa spawn con un array de argumentos.

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, sin shell)

spawn() lanza un proceso con un array de argumentos (sin shell) y transmite stdout/stderr — seguro y eficiente en memoria para salida grande o de larga ejecución. Como los argumentos se pasan directamente (no por un shell), no hay expansión de globs ni riesgo de inyección. Encadena los streams del hijo a otros streams 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 y fork

execFile corre un ejecutable sin shell — más seguro que exec para ejecutar un binario conocido con argumentos. fork() genera un proceso Node y abre un canal IPC integrado (send/on('message')), la base del paso de mensajes entre procesos Node tipo cluster y worker_threads.

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 y argumentos

stdio controla los flujos estándar del hijo: 'inherit' comparte la terminal del padre (genial para scripts de npm), 'ignore' descarta, 'pipe' captura. detached + unref() genera un proceso en segundo plano que sobrevive al padre. Pasa los argumentos como array — spawn los entrecomilla por ti, así que los espacios y caracteres especiales son 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 salida y señales

El evento 'exit' reporta el código (null si lo mató una señal) y la señal (null en salida normal). 'close' se dispara después de que los flujos stdio se hayan cerrado — úsalo cuando has encadenado la salida con pipe y necesitas saber que los flujos se vaciaron. kill() envía una señal; SIGTERM es elegante, SIGKILL no se puede capturar.

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 te permite generar varios procesos Node compartiendo un puerto, escalando entre núcleos de CPU. El primario genera workers (típicamente os.cpus().length). Cada worker es un proceso Node completo corriendo el mismo script. Reinicia workers en 'exit' por resiliencia. Usa cluster.isPrimary (antes isMaster) para ramificar la 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);
}

Gestión de workers

El primario rastrea los workers vía los eventos 'online' (proceso arrancado), 'listening' (servidor enlazado), 'disconnect' y 'exit'. disconnect() drena las conexiones antes de matar al worker — úsalo para recargas sin tiempo de inactividad. cluster.workers mapea IDs de worker a objetos Worker para poder enviarles mensajes o cerrarlos.

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' });
}

Puerto de servidor compartido

Los workers escuchan en el mismo puerto; el primario balancea las conexiones entrantes. SCHED_RR (round-robin, por defecto en la mayoría de plataformas) reparte uniformemente; SCHED_NONE lo deja al sistema operativo. El estado NO se comparte entre workers — usa Redis o una base de datos para sesiones/caché compartidas.

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 del worker e IPC

cluster.fork() abre un canal IPC (como child_process.fork): worker.send y process.on('message') intercambian JSON entre primario y workers. Úsalo para despachar trabajos o señalizar apagado elegante. Para trabajo intensivo de CPU considera también worker_threads, que comparten memoria y evitan la sobrecarga del 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));
  }
});

Recarga elegante (sin tiempo de inactividad)

Un reinicio rodante recarga los workers uno a uno para que la app nunca se caiga: desconecta un worker (deja de aceptar conexiones nuevas), espera a que salga tras drenar, y luego genera un reemplazo. Dispara con SIGHUP. Combínalo siempre con un mensaje de 'shutdown' por worker para que cada uno cierre su servidor y salga solo tras terminar las peticiones en curso.

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

Programación asíncrona

Callbacks y convención error-first

El patrón asíncrono clásico de Node es el callback error-first: el primer argumento es un error (null en éxito) y los siguientes son resultados. Comprueba siempre err primero y retorna temprano ante fallo. Este estilo escala mal con el anidamiento — conocido como callback hell — así que el código moderno usa Promises y 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

Una Promise representa un valor futuro. then() maneja el éxito, catch() el rechazo, finally() corre en ambos casos. Encadena then() para transformar valores secuencialmente. util.promisify convierte una función de callback error-first en una que devuelve una Promise — uniendo las APIs heredadas a 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 hace que el código asíncrono parezca sincrónico. Una función async devuelve una Promise; await pausa hasta que se resuelva. Envuelve las llamadas esperadas en try/catch para manejar rechazos. El await de nivel superior está permitido en módulos ES y (con un flag) en CommonJS, eliminando la necesidad del envoltorio IIFE asíncrono.

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 y allSettled

Promise.all corre promesas en paralelo y se resuelve con un array de resultados, pero rechaza de inmediato si CUALQUIER promesa rechaza (fast-fail) — úsalo cuando todas deben tener éxito. Promise.allSettled espera a todas las promesas sin importar el desenlace, devolviendo objetos {status, value/reason} — lo mejor cuando el éxito parcial es aceptable.

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 y Promise.any

Promise.race se resuelve O rechaza con la primera promesa en liquidarse — útil para timeouts y competir espejos. Promise.any se resuelve con el primer éxito y solo rechaza (AggregateError) si toda promesa falla — ideal para endpoints redundantes donde una respuesta sana 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))
  ]);
}

Secuencial vs paralelo

Esperar en un bucle corre secuencialmente (lento). Mapea a un array de promesas y aplícales Promise.all para paralelismo (rápido, pero una concurrencia sin límite puede agotar recursos). Un pool con límite de concurrencia estrangula el trabajo paralelo — esencial al llamar APIs con rate limit o hacer I/O pesado sobre miles de ítems.

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

Manejo de errores

try/catch/finally

try/catch maneja errores sincrónicos y (con await) rechazos asíncronos. finally corre siempre, incluso ante return/throw — úsalo para limpieza como cerrar manejadores. Captura errores concretos comprobando err.code, y relanza aquello que no reconozcas para que los bugs inesperados salgan a la luz en lugar de quedarse ocultos.

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

En los callbacks error-first, comprueba siempre err primero y retorna temprano — nunca uses data cuando err está fijado. Al envolver una API de callback, reenvía el error a tu propio callback en lugar de lanzar (los throws dentro de callbacks no pueden ser capturados por quien llama). Envuelve el código sincrónico que pueda lanzar (como JSON.parse) en 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); }
  });
}

Excepciones no capturadas

uncaughtException se dispara ante excepciones sincrónicas que ningún manejador captura — el proceso queda corrupto; registra, cierra el servidor y sal (deja que un gestor de procesos te reinicie). unhandledRejection se dispara por promesas olvidadas; desde Node 15 tumban el proceso, así que añade siempre .catch() o 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

Clases de error personalizadas

Hereda de Error para añadir campos estructurados (code, field, status) y distinguir tipos de error con instanceof. Fja siempre this.name al nombre de la clase (no es automático en objetivos antiguos) y llama a super(message). Los errores personalizados hacen legibles los bloques catch: ramifica con instanceof en lugar de con comparación frágil de cadenas.

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;
  }
}

Propiedades de error y cause

Cada Error tiene message, name y stack. Añade una propiedad code para un manejo estable y legible por máquina (los propios errores de Node usan códigos como ENOENT, EACCES). La opción cause de ES2022 (Node 16.9+) encadena un error subyacente para poder envolver fallos de bajo nivel conservando el stack original para depurar.

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 y limpieza

Usa 'beforeExit' para limpieza asíncrona (puede posponer la salida), y 'exit' solo para trabajo sincrónico. Maneja SIGTERM (apagado de contenedor) y SIGINT (Ctrl-C) para drenar conexiones antes de salir — añade un timeout de salida forzada para que una conexión atascada no cuelgue el proceso. Domains está obsoleto; usa try/catch y manejo de errores así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

Depuración

Funciones de console

console ofrece más que log: table renderiza arrays de objetos, time/timeEnd mide duraciones, dir vuelca un objeto con profundidad configurable, trace imprime un stack y count lleva la cuenta de visitas. Usa console.error (stderr) para que los logs y los errores puedan separarse en pipelines de producción.

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 y DevTools

--inspect arranca el inspector de V8 para que Chrome DevTools (chrome://inspect) o VS Code se conecten. --inspect-brk pausa en la primera línea para poder fijar breakpoints antes de que corra el código de arranque. El clásico 'node inspect' es un depurador de terminal útil sobre SSH donde no hay navegador disponible.

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

La sentencia debugger

La sentencia debugger pausa la ejecución SOLO cuando hay un depurador (DevTools o VS Code) conectado — de lo contrario es un no-op, seguro de dejar en el código. Combínala con --inspect-brk para detenerse al arrancar. Para inspección ad-hoc, suelta debugger; dentro de bucles o condiciones en lugar de fijar breakpoints en la 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; }

Depuración en VS Code

El depurador de Node de VS Code (F5) lee .vscode/launch.json. "request": "launch" corre el programa con el inspector integrado; "attach" se conecta a un proceso ya arrancado con --inspect. skipFiles oculta los internos de Node al depurar paso a paso. Usa el flag "restart" o nodemon para relanzar automáticamente ante cambios de archivos.

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

Advertencias y stack traces

--trace-warnings imprime stacks para las advertencias del proceso (fugas de memoria, APIs obsoletas). --trace-deprecation hace visibles los usos de APIs heredadas; --throw-deprecation los convierte en errores duros para un CI más estricto. --cpu-prof escribe un perfil que puedes abrir en Chrome DevTools para hallar las funciones calientes. Sube Error.stackTraceLimit para traces asíncronos más 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

Hasheo (createHash)

createHash produce un resumen unidireccional. SHA-256 es el valor por defecto moderno para checksums y firmas; evita MD5/SHA-1 por seguridad (propensos a colisiones). Puedes alimentar los datos de forma incremental y transmitir archivos grandes sin guardarlos en búfer. digest('hex') devuelve una cadena hex; 'base64' también es común. Hashear NO es almacenar contraseñas — usa 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 firma datos con un secreto compartido para que quien reciba pueda verificar tanto la integridad como la autenticidad. Es la base de las firmas JWT y de la verificación de webhooks (GitHub, Stripe). Compara siempre las firmas con timingSafeEqual — un === normal filtra información por diferencias de tiempo que los atacantes pueden explotar.

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 aleatorios

crypto.randomBytes produce datos aleatorios criptográficamente seguros — úsalo para tokens, IDs y secretos. La forma asíncrona evita bloquear el event loop al generar muchos bytes. crypto.randomInt da enteros aleatorios sin sesgo, y randomUUID() genera UUIDs v4 RFC-4122. Nunca uses Math.random() para nada relacionado con seguridad.

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!

Cifrado (createCipheriv)

AES-256-GCM es el cifrado simétrico recomendado — es autenticado, así que la manipulación se detecta. El IV (nonce) debe ser único por cifrado con una clave dada (nunca lo reutilices); guárdalo junto al texto cifrado. setAuthTag verifica la integridad al descifrar. Nunca uses el obsoleto createCipher (deriva claves de forma insegura) — usa siempre createCipheriv con una clave adecuada.

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');
}

Hasheo de contraseñas (pbkdf2, scrypt)

Hashea las contraseñas con un KDF lento y salado — nunca con un hash plano. pbkdf2 (ajusta las iteraciones hacia arriba a medida que mejora el hardware) y scrypt (memory-hard, resistente a GPU) vienen integrados en Node. Guarda iteraciones, sal y hash juntos para poder verificar y actualizar parámetros más tarde. Usa timingSafeEqual para comprobar hashes sin filtrar información de tiempos.

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);
}

Comparación segura en tiempo

timingSafeEqual compara dos buffers en tiempo constante, previniendo ataques de temporización donde un atacante infiere un secreto byte a byte a partir de los retrasos de respuesta. Ambos buffers deben tener la misma longitud (compruébalo primero, pero esa comprobación de longitud en sí puede filtrar la longitud — para secretos, hashea ambos lados primero). Úsalo siempre que compares tokens, firmas o API keys.

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

Información del sistema

os expone el entorno anfitrión. platform/arch/type identifican el sistema operativo para comprobaciones de portabilidad. os.EOL da la secuencia de fin de línea de la plataforma — úsalo al escribir archivos de texto correctos por plataforma. hostname es el nombre de red de la máquina, útil para registrar qué instancia manejó una petición.

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';

Información de CPU

os.cpus() devuelve un array de núcleos lógicos (hyperthreads incluidos), así que su longitud es la pista de concurrencia correcta para cluster.fork. Cada entrada tiene model, speed y times (user/sys/idle). loadavg reporta la carga del sistema (solo Linux/macOS) — un valor por encima de cpus().length sugiere saturación.

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);

Memoria

os.totalmem/freemem reportan la RAM del sistema, mientras que process.memoryUsage reporta la huella de este proceso. rss es la memoria a nivel de sistema operativo; heapUsed son los objetos JS vivos. Vigila heapUsed para detectar fugas. Para convertir bytes a MB, divide entre 1024*1024 (1048576). Ajusta --max-old-space-size cuando el heap crezca cerca del límite.

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 red

os.networkInterfaces() lista cada interfaz de red con sus direcciones, MAC y familia (IPv4/IPv6). El flag 'internal' marca loopback. Es la forma portable de descubrir la IP LAN de la máquina para enlazar servidores o registrar. Cada interfaz puede tener varias direcciones (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';
}

Usuario y rutas

os.homedir devuelve el directorio home del usuario y os.tmpdir la carpeta temporal del sistema — ambos conscientes de la plataforma, así que prefírelos a rutas fijadas a fuego. os.userInfo da la identidad del usuario actual. os.constants centraliza los valores numéricos de señal/errno/prioridad para que no fijes 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 los argumentos de línea de comandos: argv[0] es el binario node, argv[1] el script, y el resto son argumentos del usuario. Corta los dos primeros para obtener solo los del usuario. Para algo más allá de scripts de juguete, usa un parser como minimist, yargs o commander — manejan flags, tipos, valores por defecto y texto de ayuda.

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 las variables de entorno como cadenas. Convencionalmente PORT, NODE_ENV, DATABASE_URL y API_KEY vienen del env para que el mismo código corra en cualquier entorno. Usa el paquete dotenv para cargar un archivo .env en desarrollo. Nunca subas secretos al repositorio — inyéctalos vía el entorno del 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 y códigos de salida

process.exit(n) termina de inmediato, posiblemente antes de que se vacíen los búferes de I/O — prefiere fijar process.exitCode y dejar que el event loop drene naturalmente. Salir con 0 significa éxito; no cero señala fallo a shells y CI. La convención 128+N codifica la terminación por la señal N (así SIGTERM da 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 y process.stderr son streams escribibles — write() no añade salto de línea (a diferencia de console.log). stdin es un stream legible que puedes consumir con eventos 'data' o iteración asíncrona (el patrón moderno más limpio). Usa stderr para diagnósticos para poder separarlo de la salida real en 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 del proceso (señales)

'exit' se dispara tras vaciarse el event loop — ahí solo corre código sincrónico. 'beforeExit' puede correr trabajo asíncrono y puede posponer la salida. Maneja SIGINT (Ctrl-C) y SIGTERM (docker stop, kill) para cerrar servidores y conexiones de base de datos con elegancia. Fja siempre un timeout de salida forzada para que una conexión colgada no atrape al proceso para siempre.

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 y uptime

process expone identidad (pid, ppid, platform, version) y estadísticas de runtime (uptime, memoryUsage, cpuUsage). cwd() es el directorio de trabajo — chdir lo cambia, afectando a la resolución de rutas relativas. memoryUsage y cpuUsage son la base de los endpoints de health check y las métricas de autoescalado.

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

Red (net)

Servidor TCP

net.createServer crea un servidor TCP crudo. Cada conexión invoca al callback con un Socket (un stream Duplex). Lee con eventos 'data', escribe con socket.write. Maneja siempre 'error' en los sockets o el proceso se tumba. TCP es la fundación bajo HTTP — útil para protocolos personalizados, juegos y 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 (alias createConnection) abre un socket cliente TCP. El callback se dispara al conectar; los eventos 'data' entregan los bytes entrantes. Fja una codificación para recibir cadenas en lugar de Buffers. Como cualquier stream, maneja 'error' para evitar caídas. Los sockets se cierran solos en 'end'; llama a client.end() para hacer half-close de tu 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 y datos del socket

TCP es un flujo de bytes, no un protocolo de mensajes — un evento 'data' no equivale a un mensaje; los datos pueden partirse o fusionarse. DEBES enmarcar los mensajes tú mismo (prefijos de longitud, delimitadores o un parser). setKeepAlive detecta pares muertos, setTimeout mata conexiones inactivas y 'drain' señala que el búfer de escritura se vació.

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);

Escritura y half-close

socket.write respeta la contrapresión (devuelve false cuando está lleno — espera 'drain'). end() hace half-close: vacía las escrituras pendientes y envía FIN mientras sigue leyendo al par. destroy() mata el socket de inmediato. Usa remoteAddress/remotePort para logging y control de acceso. Pause/resume estrangulan a un emisor 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 del servidor e IPC

Un net.Server emite 'connection' (por cliente), 'listening', 'error' (maneja EADDRINUSE) y 'close'. listen puede tomar una ruta para un socket Unix (o pipe con nombre en Windows) — IPC local rápido y seguro entre procesos del mismo host. server.close() deja de aceptar conexiones nuevas y espera a que terminen las existentes.

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

Temporizadores y utilidades

Temporizadores (setTimeout, setInterval)

setTimeout corre una vez tras un retardo, setInterval repite. setImmediate corre después de los eventos de I/O en el mismo giro del loop. queueMicrotask corre incluso antes, justo después de la operación actual. El orden dentro de un loop es: microtareas primero, luego temporizadores, luego I/O, luego setImmediate — útil saberlo al programar trabajo posterior.

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)

Limpiar temporizadores y ref

Cada temporizador tiene su función clear correspondiente. unref() marca un temporizador como 'no mantener vivo el proceso' — si solo quedan temporizadores unref'd, Node sale (práctico para limpieza periódica que no deba atrapar al proceso). ref() lo revierte. Los argumentos extra tras el retardo se reenvían al callback, evitando una función flecha 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 y format

util.format construye cadenas con placeholders estilo printf (%s %d %j %o %O %%). util.inspect renderiza cualquier objeto — pasa { depth: null, colors: true } para un volcado completo y coloreado, útil en logs. util.deprecate envuelve una función para emitir una DeprecationWarning (visible con --trace-deprecation) al llamarse.

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 envuelve una función de callback error-first en una que devuelve Promise — el puente de las APIs heredadas de callback a async/await. Muchos módulos del núcleo ya traen versiones de promesa nativas (fs/promises) que son preferibles, pero promisify aún rescata APIs de callback de terceros. Una función puede definir [util.promisify.custom] para controlar la conversión.

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 de util y callbackify

util.types ofrece comprobaciones de tipo fiables (isPromise, isAsyncFunction, isRegExp, isMap) que sobreviven mejor a los casos límite de cross-realm y subclases que instanceof. util.callbackify es el inverso de promisify — útil cuando debes exponer una función basada en promesas a una API estilo callback. util.MIMEType (Node 19+) parsea y 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 corre justo después de la operación sincrónica actual, ANTES de la I/O — así que llamar recursivamente a nextTick puede dejar a la I/O sin alimento indefinidamente (el loop nunca avanza). setImmediate corre después de la I/O, en la fase 'check'. Para ceder al event loop y dejar que la I/O pendiente se asiente, prefiere setImmediate; reserva nextTick para la limpieza que debe ocurrir antes de cualquier 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.