Patrones de Scripts de Utilidad

Patrones comunes para escribir scripts de utilidad en Node.js - E/S de archivos, globbing, salida coloreada, indicaciones interactivas y spinners.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

# Instala el kit de herramientas de scripts de utilidad estándar
npm install --save-dev \
  fast-glob \
  chalk \
  @inquirer/prompts \
  ora
 
# Integrados de Node - no se requiere instalación
#   node:fs/promises   - E/S de archivos asincrónica
#   node:path          - rutas multiplataforma
#   node:url           - fileURLToPath para __dirname en ESM

// Esqueleto mínimo
import { readFile, writeFile } from "node:fs/promises";
import fg from "fast-glob";
import chalk from "chalk";
import { confirm } from "@inquirer/prompts";
import ora from "ora";

Cuándo usarlo: Cualquier utilidad CLI, codemod, paso de construcción o script de mantenimiento donde necesites retroalimentación de progreso y operaciones de archivo seguras.

Ejemplo Funcional

// scripts/process-ts-files.ts
import { readFile, writeFile } from "node:fs/promises";
import path from "node:path";
import fg from "fast-glob";
import chalk from "chalk";
import { confirm } from "@inquirer/prompts";
import ora from "ora";
 
async function main(): Promise<void> {
  // 1. Busca archivos
  const files = await fg("src/**/*.ts", {
    ignore: ["**/*.d.ts", "**/node_modules/**"],
    absolute: true,
  });
 
  console.log(chalk.cyan(`Se encontraron ${files.length} archivos TypeScript.`));
 
  if (files.length === 0) {
    console.log(chalk.yellow("Nada que hacer."));
    return;
  }
 
  // 2. Confirma con el usuario
  const proceed = await confirm({
    message: `¿Procesar ${files.length} archivos?`,
    default: false,
  });
 
  if (!proceed) {
    console.log(chalk.gray("Abortado."));
    return;
  }
 
  // 3. Procesa con un spinner
  const spinner = ora("Procesando archivos...").start();
  let changed = 0;
 
  try {
    for (const file of files) {
      const contents = await readFile(file, "utf8");
      const next = contents.replace(/\r\n/g, "\n");
      if (next !== contents) {
        await writeFile(file, next, "utf8");
        changed += 1;
      }
      spinner.text = `Procesando ${path.basename(file)}`;
    }
    spinner.succeed(chalk.green(`Normalizados ${changed} archivo(s).`));
  } catch (err) {
    spinner.fail(chalk.red("Error al procesar."));
    throw err;
  }
}
 
main().catch((err: unknown) => {
  console.error(chalk.red("Error de script:"), err);
  process.exitCode = 1;
});

Qué demuestra esto:

• E/S de archivos asincrónica vía node:fs/promises (nunca readFileSync en un script asincrónico)
• fast-glob para coincidencia de archivos rápida y flexible con patrones ignore
• API de función nombrada de @inquirer/prompts (reemplaza la API de objeto antigua de inquirer.prompt())
• Spinner ora con actualizaciones de text dinámicas y estados succeed / fail
• Manejo de errores adecuado que establece process.exitCode en lugar de llamar a process.exit()

Profundización

Cómo funciona

• node:fs/promises expone todas las funciones fs como variantes que devuelven promesas. Ya no se necesita util.promisify.
• fast-glob es la librería glob más rápida y ampliamente utilizada para Node. Devuelve un string[] simple por defecto (o Entry[] con objectMode: true).
• chalk v5 es solo ESM. Si estás en CommonJS, fija chalk v4 o convierte tu proyecto a ESM.
• @inquirer/prompts es el reemplazo moderno del paquete monolítico inquirer. Cada prompt (input, confirm, select, checkbox) se importa como una función nombrada que devuelve una promesa.
• ora escribe en stderr por defecto y detecta TTY para desactivar animaciones en CI. Puedes forzar el estado vía { isEnabled: process.stdout.isTTY }.

Variaciones

Lectura y escritura de archivos JSON:

import { readFile, writeFile } from "node:fs/promises";
 
interface Config {
  name: string;
  version: string;
}
 
const raw = await readFile("config.json", "utf8");
const config = JSON.parse(raw) as Config;
config.version = "2.0.0";
await writeFile("config.json", JSON.stringify(config, null, 2) + "\n");

Procesamiento basado en streams para archivos grandes:

import { createReadStream } from "node:fs";
import { createInterface } from "node:readline";
 
const rl = createInterface({
  input: createReadStream("huge.log"),
  crlfDelay: Infinity,
});
 
for await (const line of rl) {
  // procesa una línea a la vez - la memoria se mantiene plana
}

Recorrido recursivo de directorios sin una librería glob:

import { readdir } from "node:fs/promises";
 
// Node 20+ admite recursive: true
const entries = await readdir("src", { recursive: true, withFileTypes: true });
const files = entries.filter((e) => e.isFile()).map((e) => e.name);

Barras de progreso con cli-progress:

import cliProgress from "cli-progress";
 
const bar = new cliProgress.SingleBar({}, cliProgress.Presets.shades_classic);
bar.start(files.length, 0);
for (const file of files) {
  await process(file);
  bar.increment();
}
bar.stop();

Detectando TTY para silenciar la decoración en CI:

const isInteractive = process.stdout.isTTY && !process.env.CI;
const spinner = ora({ text: "Working...", isEnabled: isInteractive });

Cadenas de plantilla con chalk:

console.log(`${chalk.bold.blue("info")} Found ${chalk.yellow(files.length)} files`);

Notas de TypeScript

• fs.readFile(path, "utf8") devuelve Promise<string>. Sin la codificación, devuelve Promise<Buffer>. Siempre pasa "utf8" cuando quieras una cadena.
• fast-glob devuelve Promise<string[]> cuando se llama sin opciones. Con { objectMode: true } devuelve Promise<Entry[]>.
• @inquirer/prompts infiere tipos de devolución desde el prompt: confirm() devuelve Promise<boolean>, input() devuelve Promise<string>, y select<T>() acepta un genérico para el valor de la opción.
• Escribe el manejador de error de script de nivel superior como (err: unknown) y reduce antes de registrar.

Trampas

Cosas que te atraparán. Cada trampa incluye qué sale mal, por qué sucede y la solución.

• Usar fs.readFileSync en un script asincrónico - Bloquea el event loop, anula la concurrencia y hace que los spinners se entrecorten. Solución: Usa import { readFile } from "node:fs/promises" y await. Las APIs sincrónicas solo son apropiadas en código de inicio antes de cualquier trabajo asincrónico.

• Olvidar await en una llamada de fs.promises - writeFile(path, data) sin await devuelve una promesa sin controlar. El script se cierra antes de que se complete la escritura, perdiendo datos silenciosamente. Solución: Siempre await, y activa @typescript-eslint/no-floating-promises para detectar esto en tiempo de lint.

• Los colores de chalk no aparecen en CI - Chalk detecta automáticamente TTY y desactiva los colores en entornos no interactivos. Los registros en GitHub Actions o CircleCI aparecen sin colorear por diseño. Solución: Establece FORCE_COLOR=1 como variable de entorno en CI, o usa new Chalk(\{ level: 3 \}) para forzar el nivel de color.

• Rutas relativas vs absolutas en glob - fast-glob devuelve rutas relativas a cwd por defecto. Pasar esas a fs.readFile funciona solo si el script se ejecuta desde el mismo directorio. Solución: Usa { absolute: true } o resuelve manualmente con path.resolve(process.cwd(), file).

• Emoji rompiendo terminales de Windows - cmd.exe heredada y PowerShell más antiguos renderizan emoji como bytes garrapateados. Solución: Detecta Windows vía process.platform === "win32" y recurre a ASCII, o requiere Windows Terminal (UTF-8 por defecto).

• Llamar process.exit() antes de que las escrituras se vacíen - process.exit(1) termina inmediatamente, truncando escrituras de stdout y llamadas de fs.writeFile pendientes. Solución: Establece process.exitCode = 1 y deja que el event loop se drene naturalmente.

Alternativas

Otras formas de resolver el mismo problema - y cuándo cada una es la mejor opción.

Preguntas frecuentes

Relacionado

• ESLint for Node.js Scripts - lint tus scripts con reglas conscientes de tipos
• Git Utilities - herramientas de shell para scripts de automatización
• TypeScript Basics - tsconfig para proyectos de Node
• Environment Variables - cargando configuración en scripts