JSONL en JavaScript: leer, escribir y parsear
Una guía completa para trabajar con archivos JSONL (JSON Lines) en JavaScript. Aprende a leer, escribir, parsear y procesar datos JSONL en streaming, tanto en Node.js como en el navegador, con las API nativas y las bibliotecas más populares.
¿Por qué usar JavaScript para trabajar con JSONL?
JavaScript es una opción natural para trabajar con archivos JSONL. El propio formato JSON nació de JavaScript, por lo que el lenguaje ofrece soporte nativo para parsearlo y serializarlo mediante los métodos JSON.parse() y JSON.stringify(). Tanto si estás creando un pipeline de datos en Node.js como si procesas archivos de registro en un servidor o permites que los usuarios carguen archivos JSONL en el navegador, JavaScript te ofrece las herramientas necesarias en cada paso.
JSONL (JSON Lines) almacena un objeto JSON por línea, lo que lo hace ideal para el streaming, los registros en los que solo se añaden entradas y el procesamiento de grandes conjuntos de datos línea a línea. Los streams de Node.js encajan perfectamente con este formato y te permiten leer y transformar millones de registros sin agotar la memoria. En el cliente, las API FileReader y Streams del navegador permiten procesar JSONL íntegramente en el dispositivo del usuario. En esta guía aprenderás a leer JSONL tanto en Node.js como en el navegador, escribir archivos JSONL, crear pipelines de transformación con streams y elegir la biblioteca de npm más adecuada para tu proyecto.
Leer JSONL en Node.js
Node.js incluye el módulo readline para leer archivos línea a línea de forma eficiente. Combinado con fs.createReadStream, es la opción recomendada para procesar archivos JSONL en el servidor, ya que lee los datos en streaming en lugar de cargar todo el archivo en memoria.
Usa fs.createReadStream como entrada de readline.createInterface para leer un archivo JSONL línea a línea. Este enfoque consume muy poca memoria, independientemente del tamaño del archivo.
import { createReadStream } from 'node:fs';
import { createInterface } from 'node:readline';
async function readJsonl(filePath) {
const records = [];
const rl = createInterface({
input: createReadStream(filePath, 'utf-8'),
crlfDelay: Infinity,
});
for await (const line of rl) {
const trimmed = line.trim();
if (trimmed) {
records.push(JSON.parse(trimmed));
}
}
return records;
}
// Usage
const data = await readJsonl('data.jsonl');
console.log(`Loaded ${data.length} records`);
console.log(data[0]);Si el archivo JSONL es pequeño y cabe holgadamente en memoria, puedes leerlo entero de una vez y dividir su contenido por los saltos de línea. Así simplificas el código a costa de la eficiencia del streaming.
import { readFileSync } from 'node:fs';
const records = readFileSync('data.jsonl', 'utf-8')
.split('\n')
.filter(line => line.trim())
.map(line => JSON.parse(line));
console.log(`Loaded ${records.length} records`);Leer JSONL en el navegador
En el navegador, los usuarios pueden cargar archivos JSONL mediante un campo de selección de archivos. Puedes leerlos con la API FileReader o con la API Streams, más moderna, sin enviar ningún dato a un servidor.
Usa FileReader para leer un archivo seleccionado por el usuario; después, divide el texto en líneas y parsea cada una. Todos los datos se mantienen en el cliente para proteger su privacidad.
function parseJsonlFile(file) {
return new Promise((resolve, reject) => {
const reader = new FileReader();
reader.onload = () => {
const text = reader.result;
const records = text
.split('\n')
.filter(line => line.trim())
.map(line => JSON.parse(line));
resolve(records);
};
reader.onerror = () => reject(reader.error);
reader.readAsText(file, 'utf-8');
});
}
// Usage with an <input type="file"> element
const input = document.querySelector('input[type="file"]');
input.addEventListener('change', async (e) => {
const file = e.target.files[0];
const records = await parseJsonlFile(file);
console.log(`Parsed ${records.length} records`);
});Para trabajar con archivos grandes en el navegador, usa la API Streams junto con TextDecoderStream y procesa el archivo por bloques. Así evitas cargarlo entero en memoria de una sola vez.
async function* streamJsonl(file) {
const stream = file.stream()
.pipeThrough(new TextDecoderStream());
const reader = stream.getReader();
let buffer = '';
while (true) {
const { done, value } = await reader.read();
if (done) break;
buffer += value;
const lines = buffer.split('\n');
buffer = lines.pop(); // Keep incomplete last line
for (const line of lines) {
const trimmed = line.trim();
if (trimmed) yield JSON.parse(trimmed);
}
}
// Handle remaining buffer
if (buffer.trim()) {
yield JSON.parse(buffer.trim());
}
}
// Usage
for await (const record of streamJsonl(file)) {
console.log(record);
}Escribir JSONL en Node.js
Escribir archivos JSONL en Node.js es sencillo: serializa cada objeto JavaScript como una cadena JSON y añade un salto de línea. Para obtener el mejor rendimiento con grandes conjuntos de datos, usa un stream de escritura en lugar de construir toda la cadena en memoria.
Usa fs.writeFileSync o fs.createWriteStream para escribir registros en un archivo JSONL. Cada registro ocupa una única línea de JSON válido, seguida de un salto de línea.
import { writeFileSync } from 'node:fs';
const records = [
{ id: 1, name: 'Alice', role: 'engineer' },
{ id: 2, name: 'Bob', role: 'designer' },
{ id: 3, name: 'Charlie', role: 'manager' },
];
const jsonl = records
.map(record => JSON.stringify(record))
.join('\n') + '\n';
writeFileSync('output.jsonl', jsonl, 'utf-8');
console.log(`Wrote ${records.length} records`);Cuando tengas que escribir millones de registros, usa un stream de escritura para evitar construir toda la cadena de salida en memoria. El stream gestiona automáticamente la contrapresión (backpressure) y pausa las escrituras cuando se llena el búfer del sistema operativo.
import { createWriteStream } from 'node:fs';
async function writeJsonl(filePath, records) {
const stream = createWriteStream(filePath, 'utf-8');
for (const record of records) {
const line = JSON.stringify(record) + '\n';
// Respect backpressure
if (!stream.write(line)) {
await new Promise(resolve => stream.once('drain', resolve));
}
}
stream.end();
await new Promise(resolve => stream.on('finish', resolve));
console.log('Write complete');
}
// Usage
const data = Array.from({ length: 100000 }, (_, i) => ({
id: i + 1,
value: Math.random(),
timestamp: new Date().toISOString(),
}));
await writeJsonl('large_output.jsonl', data);Streams Transform para pipelines de JSONL
Los streams Transform de Node.js te permiten crear pipelines de datos a partir de etapas que puedes combinar para leer JSONL, procesar cada registro y escribir los resultados. Este patrón es ideal para tareas ETL, procesamiento de logs y migraciones de datos.
import { createReadStream, createWriteStream } from 'node:fs';
import { createInterface } from 'node:readline';
import { Transform } from 'node:stream';
import { pipeline } from 'node:stream/promises';
// Transform: parse JSONL line into object, process, stringify back
const transformJsonl = new Transform({
objectMode: true,
transform(chunk, encoding, callback) {
const line = chunk.toString().trim();
if (!line) return callback();
try {
const record = JSON.parse(line);
// Add your transformation here
record.processed = true;
record.processedAt = new Date().toISOString();
callback(null, JSON.stringify(record) + '\n');
} catch (err) {
callback(err);
}
},
});
// Build the pipeline
const rl = createInterface({
input: createReadStream('input.jsonl', 'utf-8'),
crlfDelay: Infinity,
});
const output = createWriteStream('output.jsonl', 'utf-8');
for await (const line of rl) {
transformJsonl.write(line);
}
transformJsonl.end();
await pipeline(transformJsonl, output);
console.log('Pipeline complete');Este pipeline lee un archivo JSONL línea a línea, transforma cada registro añadiendo los campos processed y processedAt, y escribe los resultados en un archivo nuevo. El stream Transform gestiona automáticamente la contrapresión, por lo que el consumo de memoria se mantiene constante incluso con archivos muy grandes. Puedes encadenar varias transformaciones para crear flujos de trabajo ETL complejos.
Bibliotecas de JavaScript para JSONL
Aunque el método nativo JSON.parse resuelve bien la mayoría de los casos, varios paquetes de npm ofrecen utilidades prácticas para tareas específicas de JSONL, como el streaming, la validación y el procesamiento por lotes.
JSON.parse (nativo)
NativoLos métodos nativos JSON.parse() y JSON.stringify() están muy optimizados en V8 y bastan para la mayoría de los usos de JSONL. Combínalos con readline para trabajar en streaming. No necesitas dependencias y el rendimiento es excelente con archivos de hasta varios cientos de MB.
ndjson
Popularndjson es un paquete popular de npm que ofrece parsers y serializadores de JSONL (Newline Delimited JSON) en streaming, compatibles con los streams de Node.js. Gestiona los errores de parseo de forma controlada y se integra bien en pipelines de streams existentes. Es una buena opción para crear prototipos rápidamente.
jsonl-parse-stringify
Simplejsonl-parse-stringify es una biblioteca ligera y sin dependencias que ofrece los sencillos métodos parse() y stringify() para trabajar con datos JSONL. Contempla casos especiales como los saltos de línea al final del archivo y las líneas vacías. Es ideal si buscas una API síncrona sencilla sin tener que configurar streams.
Prueba nuestras herramientas gratuitas para JSONL
¿Prefieres no escribir código? Usa nuestras herramientas gratuitas en línea para visualizar, convertir y formatear archivos JSONL directamente en tu navegador. Todo se procesa de forma local, así que tus datos se mantienen privados.
Aprende a transmitir datos JSONL en tiempo real con Node.js, Python, Server-Sent Events y WebSockets. Crea pipelines de streaming para logs, métricas y flujos de datos en directo.
Estrategias para procesar gigabytes de datos JSONL: lectura en streaming, gestión de memoria, división de archivos, compresión y herramientas online.
Valida archivos JSONL línea por línea. Detecta al instante errores de sintaxis, problemas de codificación y fallos de formato.
Domina las buenas prácticas de JSONL: formato, coherencia del esquema, gestión de errores, optimización del rendimiento y organización de archivos. Evita los errores habituales con ejemplos prácticos.
Guía completa para trabajar con archivos JSONL en Python. Aprende a leer, escribir y parsear JSONL con json, pandas y orjson, y a usar streaming para archivos grandes.