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.
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.jsonconconfig/production.jsonal 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.
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.
| Enfoque | Anidado | Arrays | Deps | Cuándo usarlo |
|---|---|---|---|---|
{...a, ...b} | No | Reemplaza | — | Configs planas |
deepMerge (arriba) | Sí | Reemplaza | — | La mayoría de fusiones de config |
_.merge | Sí | Reemplaza | lodash | Default muy probado |
_.mergeWith | Sí | Customizer | lodash | Concat/dedupe de arrays |
JSONStream | Solo concat | Concat | JSONStream | Archivos > 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 enproduction.jsonenmascara 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 conrequire: Node cachea los módulos, así que mutar el resultado de unrequirecontamina cualquier import posterior de ese archivo
Errores Comunes
- Spread sobre config anidada:
{...a, ...b}elimina en silencio las claves anidadas dea typeofcomo chequeo de objeto:typeof null === "object"rompe los merges recursivos ingenuos; excluyenullyArrayexplícitamente- Saltarse
__proto__: las claves sin filtrar permiten que un archivo no confiable enveneneObject.prototypepara todo el proceso try/catchsobre JSON conrequire:require("./x.json")lanza error con JSON inválido igual queJSON.parse; se maneja igualawaitde nivel superior en CJS: solo es legal en ESM o dentro de funcionesasync; un.jsconrequirees 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.
Recursos Relacionados
Fusionar Archivos JSON
Cómo fusionar múltiples archivos JSON en un solo objeto o array en Python, Java y JavaScript.
RecipeComparar objetos JSON
Cómo comparar dos objetos JSON y encontrar las diferencias en Python, Java y JavaScript.
RecipeAplanar y Reconstruir Objetos con Python, JS y Java
Cómo convertir objetos anidados en pares clave-valor planos y reconstruirlos, con soporte de notación por puntos, corchetes y separadores personalizados.
RecipeConvertir JSON a CSV
Cómo convertir datos JSON a formato CSV en Python, Java y JavaScript: aplana objetos anidados, desenrolla arrays y genera salida lista para Excel.
RecipeConvertir CSV a JSON
Convertí archivos CSV a JSON estructurado con Python, JavaScript y Java. Elegí la librería adecuada para conversiones puntuales o pipelines grandes.
RecipeAnalizar Archivos CSV
Cómo analizar archivos CSV en Python, Java y JavaScript con ejemplos de código prácticos.