Работа с CSV в TypeScript: парсинг и генерация

Работа с CSV в TypeScript: полное руководство

CSV (Comma-Separated Values) — один из самых распространённых форматов для обмена табличными данными. В экосистеме TypeScript существует несколько зрелых библиотек, которые позволяют эффективно парсить, генерировать и трансформировать CSV-файлы с полной поддержкой типов. В этой статье мы рассмотрим три основных инструмента: csv-parse, csv-stringify и papaparse, а также разберём практические примеры их использования.

1. Библиотека csv-parse: парсинг CSV с типизацией

csv-parse — это часть экосистемы csv.js, одна из самых производительных библиотек для разбора CSV. Она поддерживает потоки (streams), кастомные разделители и строгую типизацию через TypeScript.

Установка:

npm install csv-parse
npm install @types/csv-parse  // для TypeScript (если не включены автоматически)

Пример парсинга строки CSV:

import { parse } from 'csv-parse/sync';
import { stringify } from 'csv-stringify/sync';

interface User {
  id: number;
  name: string;
  email: string;
  age: number;
}

const csvData = `id,name,email,age
1,Иван Иванов,ivan@example.com,30
2,Мария Петрова,maria@example.com,25
3,Алексей Смирнов,alex@example.com,35`;

// Парсинг с явным указанием типов
const records: User[] = parse(csvData, {
  columns: true,      // первая строка — заголовки
  skip_empty_lines: true,
  delimiter: ',',
  cast: true          // автоматическое приведение типов (строки в числа)
});

console.log(records);
// [
//   { id: 1, name: 'Иван Иванов', email: 'ivan@example.com', age: 30 },
//   { id: 2, name: 'Мария Петрова', email: 'maria@example.com', age: 25 },
//   { id: 3, name: 'Алексей Смирнов', email: 'alex@example.com', age: 35 }
// ]

2. Библиотека csv-stringify: генерация CSV из объектов

csv-stringify — парная библиотека для создания CSV-строк и файлов из массивов объектов или кортежей. Отлично подходит для экспорта данных.

Пример генерации CSV:

import { stringify } from 'csv-stringify/sync';

interface Product {
  sku: string;
  price: number;
  stock: number;
}

const products: Product[] = [
  { sku: 'PRD-001', price: 1500, stock: 10 },
  { sku: 'PRD-002', price: 2500, stock: 5 },
  { sku: 'PRD-003', price: 800, stock: 20 },
];

const csvOutput = stringify(products, {
  header: true,
  columns: ['sku', 'price', 'stock'], // порядок и фильтрация полей
});

console.log(csvOutput);
// sku,price,stock
// PRD-001,1500,10
// PRD-002,2500,5
// PRD-003,800,20

3. Библиотека PapaParse: универсальный парсер для браузера и Node.js

PapaParse — самая популярная библиотека для работы с CSV в JavaScript/TypeScript. Она работает как в браузере, так и в Node.js, поддерживает большие файлы через потоки, автоматическое определение разделителя и обработку ошибок.

Установка:

npm install papaparse
npm install @types/papaparse

Пример с обработкой файла в Node.js:

import fs from 'fs';
import Papa from 'papaparse';

interface Transaction {
  date: string;
  amount: number;
  category: string;
}

const fileContent = fs.readFileSync('transactions.csv', 'utf-8');

const result = Papa.parse<Transaction>(fileContent, {
  header: true,
  dynamicTyping: true,  // автоматическое преобразование типов
  skipEmptyLines: true,
});

if (result.errors.length > 0) {
  console.error('Ошибки парсинга:', result.errors);
} else {
  console.log('Транзакции:', result.data);
  // result.data — массив объектов Transaction
}

// Асинхронный парсинг с потоками для больших файлов
const stream = fs.createReadStream('large-file.csv');
Papa.parse(stream, {
  header: true,
  dynamicTyping: true,
  step: (row) => {
    // Обработка каждой строки по мере чтения
    console.log('Строка:', row.data);
  },
  complete: () => {
    console.log('Парсинг завершён');
  },
});