StackPractices
intermediate Por Mathias Paulenko

Fusionar Archivos JSON en JavaScript

Cómo combinar múltiples archivos JSON en Node.js con resolución de conflictos, variantes ESM/CJS y streaming para entradas grandes.

Temas: data

Visión General

Los proyectos Node.js dividen la configuración JSON en varios archivos (uno por entorno, por módulo, por locale) y los fusionan al arrancar o en el build. Esta receta es el deep dive en Node.js: fusión multi-archivo con fs, un deepMerge blindado, variantes ESM y async, streaming para archivos que no caben en memoria y validación de la salida. Para la versión multi-lenguaje (Python, Java, jq), consulta Fusionar Archivos JSON.

Cuándo Usar

  • Combinar config/default.json con config/production.json al arrancar la app
  • Agregar respuestas paginadas de una API en un solo payload
  • Fusionar ajustes de usuario sobre valores por defecto sin perder claves anidadas
  • Construir un archivo de locale o dataset unificado en un paso de build

Si tus entradas aún no son JSON, conviértelas primero, por ejemplo con Convertir CSV a JSON. Para comprobar qué cambió realmente una fusión, pasa la salida por Comparar Objetos JSON.

Solución

Merge superficial

// CommonJS — spread de nivel superior u Object.assign, solo configs planas
const defaults = require("./config/default.json");
const prod = require("./config/production.json");

const config = { ...defaults, ...prod };
// las claves de prod reemplazan las de defaults solo en el nivel superior

El spread reemplaza los objetos anidados por completo: {db: {host, port}} de defaults desaparece entero si prod define {db: {port}}. Vale para archivos planos; es incorrecto para configuración anidada.

Deep merge (sin dependencias)

const isPlainObject = (v) =>
  v !== null && typeof v === "object" && !Array.isArray(v);
const UNSAFE_KEYS = new Set(["__proto__", "constructor", "prototype"]);

function deepMerge(target, source) {
  for (const key of Object.keys(source)) {
    if (UNSAFE_KEYS.has(key)) continue; // guarda contra prototype pollution
    if (isPlainObject(source[key]) && isPlainObject(target[key])) {
      deepMerge(target[key], source[key]);
    } else {
      target[key] = isPlainObject(source[key])
        ? deepMerge({}, source[key])
        : source[key];
    }
  }
  return target;
}

Aquí importan tres detalles. typeof null === "object", así que la guarda isPlainObject evita que un null en el override llegue a Object.keys y lance TypeError. UNSAFE_KEYS impide que {"__proto__": {...}} mute Object.prototype, un ataque real al fusionar JSON no confiable. Y la llamada deepMerge({}, source[key]) hace que las ramas fusionadas sean objetos nuevos, así las fuentes quedan intactas.

Fusionar un directorio de archivos JSON

const fs = require("fs");
const path = require("path");

function mergeJsonDir(dir) {
  return fs
    .readdirSync(dir)
    .filter((f) => f.endsWith(".json"))
    .sort() // determinista: gana el último archivo
    .reduce((acc, file) => {
      const content = JSON.parse(fs.readFileSync(path.join(dir, file), "utf-8"));
      return deepMerge(acc, content);
    }, {});
}

const config = mergeJsonDir("./config");

.sort() no es decorativo: readdirSync devuelve las entradas en orden del sistema de archivos, que varía entre máquinas. Ordenar hace que “gana el último archivo” sea predecible en CI y en los equipos de tus compañeros.

Pipeline de fusión en Node.js: leer archivos JSON ordenados, parsear cada uno, deep merge en orden, deduplicar arrays, validar contra schema y escribir la salida.

Resolución personalizada de conflictos

const _ = require("lodash");

function mergeWithResolver(sources, resolver) {
  const result = {};
  for (const source of sources) {
    for (const key of Object.keys(source)) {
      if (key in result && !_.isEqual(result[key], source[key])) {
        result[key] = resolver(key, result[key], source[key]);
      } else {
        result[key] = source[key];
      }
    }
  }
  return result;
}

// Gana el último valor, pero cada conflicto queda registrado
const merged = mergeWithResolver(
  [base, staging, production],
  (key, oldVal, newVal) => {
    console.warn(`Conflicto en "${key}": ${JSON.stringify(oldVal)} -> ${JSON.stringify(newVal)}`);
    return newVal;
  }
);

_.isEqual hace la comparación profunda que la versión ingenua se saltaba; sin ella el resolver solo ve primitivas de primer nivel.

Explicación

Una fusión son dos decisiones: hasta qué profundidad combinar y quién gana cuando las claves chocan. El merge superficial responde “reemplaza todo por debajo del primer nivel”; el deep merge recorre el árbol. La estrategia de conflicto es el segundo eje: gana-el-último es lo que hace deepMerge de forma implícita; la versión con resolver lo convierte en una elección que puedes registrar, vetar o convertir en error para checks estrictos de CI.

Los arrays merecen una mención aparte: deepMerge los reemplaza (gana la lista del override). Para fusionar datos suele interesar concatenar y deduplicar por una clave estable. _.mergeWith de lodash lo resuelve con un customizer.

En la lectura de archivos se esconden dos gotchas de Node. require("./x.json") cachea el resultado parseado en el registro de módulos, así que editar el archivo no se refleja hasta reiniciar; fs.readFileSync + JSON.parse relee cada vez, que es lo que espera un flujo con hot-reload. Y JSON.parse falla con un BOM UTF-8; algunos editores de Windows lo guardan, así que elimina un \uFEFF inicial antes de parsear si no controlas cómo se generan las entradas.

Variantes

ESM con módulos JSON y fs asíncrono

// ESM (node >= 20.10 para import attributes)
import defaults from "./config/default.json" with { type: "json" };
import fs from "node:fs/promises";

async function mergeJsonDirAsync(dir) {
  const files = (await fs.readdir(dir))
    .filter((f) => f.endsWith(".json"))
    .sort();
  let merged = {};
  for (const file of files) {
    const content = JSON.parse(await fs.readFile(new URL(`${dir}/${file}`, import.meta.url), "utf-8"));
    merged = deepMerge(merged, content);
  }
  return merged;
}

El await a nivel de módulo es legal en ESM; en CommonJS envuélvelo en un async function main(). import ... with { type: "json" } es la opción más limpia para un conjunto fijo de archivos (el análisis estático y los bundlers lo ven), pero no puede listar un directorio, así que fs sigue siendo necesario para fusiones por patrón. Mezclar ambos mundos también funciona: importa los defaults estáticamente y después haz deep merge encima con los archivos de entorno descubiertos con fs.

Arrays: concatenar en lugar de reemplazar

const merged = _.mergeWith({}, a, b, (objVal, srcVal) => {
  if (Array.isArray(objVal) && Array.isArray(srcVal)) {
    return objVal.concat(srcVal);
  }
  // undefined → vuelve al comportamiento por defecto del merge
});

Concatenar y deduplicar arrays por clave estable

function mergeRecords(sources, key = "id") {
  const seen = new Map();
  for (const source of sources) {
    for (const item of source) {
      seen.set(item[key], item); // los archivos posteriores ganan el mismo id
    }
  }
  return [...seen.values()];
}

const users = mergeRecords([batch1, batch2, batch3], "id");

Map conserva el orden de inserción, así la salida es estable y el último archivo que define un id gana su posición.

Streaming con JSONStream para archivos que no caben en memoria

const fs = require("fs");
const JSONStream = require("JSONStream");

// Fusiona arrays enormes sin cargarlos enteros
function streamMergeArrays(inputs, output) {
  const ws = fs.createWriteStream(output);
  ws.write("[");
  let first = true;
  let pending = inputs.length;
  for (const file of inputs) {
    fs.createReadStream(file)
      .pipe(JSONStream.parse("*"))
      .on("data", (item) => {
        ws.write((first ? "" : ",") + JSON.stringify(item));
        first = false;
      })
      .on("end", () => {
        if (--pending === 0) ws.end("]");
      });
  }
}

El streaming solo concatena arrays; el deep merge de objetos sigue necesitando el objeto fusionado en memoria, porque JSON no da acceso aleatorio a claves. Para datasets de más de 10k elementos considera un worker thread para que la fusión no bloquee el event loop; worker_threads ejecuta el merge en otro núcleo y devuelve el resultado.

Tolerar un archivo roto sin fallar toda la fusión

function mergeJsonDirSafe(dir) {
  const files = fs.readdirSync(dir).filter((f) => f.endsWith(".json")).sort();
  let merged = {};
  const skipped = [];
  for (const file of files) {
    try {
      merged = deepMerge(merged, JSON.parse(fs.readFileSync(path.join(dir, file), "utf-8")));
    } catch (err) {
      skipped.push({ file, error: err.message });
    }
  }
  return { merged, skipped };
}

Un archivo malformado no debería tumbar una fusión por lotes. Recoge los fallos y muéstralos: saltárselos en silencio es peor que fallar, porque un production.json perdido parece una fusión exitosa.

Validar la salida fusionada con AJV

const Ajv = require("ajv");
const schema = require("./config.schema.json");

const merged = mergeJsonDir("./config");
const valid = new Ajv({ allErrors: true }).validate(schema, merged);
if (!valid) {
  console.error(ajv.errors);
  process.exit(1);
}

allErrors: true informa de todas las violaciones en una pasada; vale la pena en un paso de build donde una config fusionada que falla en silencio se convierte en incidente en runtime.

En la práctica esa validación pertenece al CI, no al arranque. Ejecuta la fusión y el chequeo de AJV como un paso de build y falla el pipeline ante cualquier error de parseo o violación del schema: node merge.js && node validate.js. La fusión es determinista y barata, así que usarla como puerta cuesta segundos y elimina toda una clase de sorpresas de despliegue estilo “en mi máquina funcionaba”, donde un production.json roto solo explota en tiempo de ejecución.

EnfoqueAnidadoArraysDepsCuándo usarlo
{...a, ...b}NoReemplaza—Configs planas
deepMerge (arriba)SíReemplaza—La mayoría de fusiones de config
_.mergeSíReemplazalodashDefault muy probado
_.mergeWithSíCustomizerlodashConcat/dedupe de arrays
JSONStreamSolo concatConcatJSONStreamArchivos > memoria

Lo que Funciona

  • Deep merge para config, concat para datos: los árboles de configuración se fusionan en profundidad; las listas de registros se concatenan y deduplican por clave estable (id)
  • Ordena antes de fusionar: un orden determinista hace que “gana el último archivo” sea reproducible entre máquinas
  • Falla ante conflictos en CI: cambia el resolver a throw: un override silencioso en production.json enmascara errores reales
  • Valida la salida: una pasada de AJV sobre el objeto fusionado detecta claves ausentes antes del runtime
  • Mantén las fuentes inmutables: fusiona sobre {}, nunca sobre un objeto importado con require: Node cachea los módulos, así que mutar el resultado de un require contamina cualquier import posterior de ese archivo

Errores Comunes

  • Spread sobre config anidada: {...a, ...b} elimina en silencio las claves anidadas de a
  • typeof como chequeo de objeto: typeof null === "object" rompe los merges recursivos ingenuos; excluye null y Array explícitamente
  • Saltarse __proto__: las claves sin filtrar permiten que un archivo no confiable envenene Object.prototype para todo el proceso
  • try/catch sobre JSON con require: require("./x.json") lanza error con JSON inválido igual que JSON.parse; se maneja igual
  • await de nivel superior en CJS: solo es legal en ESM o dentro de funciones async; un .js con require es CJS independientemente del aspecto del código
  • Mutar un objeto de require: la caché de módulos lo comparte en todo el proceso; copia primero

Lectura Adicional

Preguntas frecuentes

¿Puedo importar un archivo JSON directamente en Node.js?

Sí — import cfg from "./app.json" with { type: "json" } en Node ≥ 20.10 (en versiones anteriores, assert en lugar de with). Se parsea una vez al cargar el módulo y es ideal para archivos de config fijos. Para directorios sigues necesitando fs.readdir + fs.readFile, porque los imports no pueden ser listas dinámicas de archivos.

¿Cómo fusiono archivos JSON de forma asíncrona?

fs/promises más deepMerge secuencial, o Promise.all para leer los archivos en paralelo y fusionar después. Mantén el paso de fusión secuencial: es CPU-bound igualmente, así que paralelizarlo no gana nada.

¿Es deepMerge seguro contra prototype pollution?

Solo si filtra las claves __proto__, constructor y prototype, como la versión de arriba. Un merge recursivo sin filtro asigna obj["__proto__"], que muta Object.prototype en todo el proceso. La alternativa es validar el JSON de entrada contra un schema antes de fusionar.

¿Debo escribir mi propio deep merge o usar lodash?

_.merge está muy probado para null, arrays, Dates y estructuras circulares; úsalo salvo que el presupuesto de dependencias sea cero. Si escribes el tuyo, copia las guardas del ejemplo; los chequeos de null/array/__proto__ son la parte que las versiones ingenuas hacen mal.

¿Cómo fusiono archivos demasiado grandes para memoria?

Concatena arrays con JSONStream (arriba); el deep merge de objetos no puede hacer streaming, porque necesita el árbol fusionado completo. Para grafos de objetos muy grandes, divide primero el archivo por clave de primer nivel con Aplanar y Desaplanar Objetos o mueve los datos a un almacén real.

¿deepMerge muta sus entradas?

La versión de arriba no: las ramas fusionadas se construyen en objetos nuevos. Ojo con las variantes que fusionan sobre target[key] in-place. Y nunca fusiones sobre un objeto JSON de require, porque la caché de módulos de Node compartiría la mutación con todos los consumidores.