العمل مع CSV في TypeScript: المكتبات وأمثلة الكود

العمل مع CSV في TypeScript: دليل شامل

CSV (قيم مفصولة بفواصل) — أحد أكثر التنسيقات شيوعًا لتبادل البيانات الجدولية. في TypeScript (و JavaScript) توجد عدة مكتبات قوية لتحليل وتوليد ومعالجة ملفات CSV. في هذه المقالة، سنستعرض الأدوات الرئيسية وإمكانياتها ونقدم أمثلة عملية.

لماذا استخدام المكتبات لـ CSV؟

الأدوات المدمجة في JavaScript (مثل split(',')) لا تأخذ في الاعتبار الحالات المعقدة:

• علامات الاقتباس والفواصل المحمية داخل الحقول
• فواصل مختلفة (فاصلة منقوطة، علامة تبويب)
• ترميزات مختلفة و BOM
• قيم متعددة الأسطر
• أنواع مختلفة لنهايات الأسطر (CRLF، LF)

المكتبات الاحترافية تحل كل هذه المشاكل وتوفر واجهة برمجة تطبيقات مريحة للعمل مع البيانات.

1. csv-parse — تحليل CSV في Node.js والمتصفح

csv-parse — جزء من نظام csv.js، وهي واحدة من أشهر مكتبات التحليل. تعمل في كل من Node.js والمتصفح (عبر bundler).

التثبيت

npm install csv-parse

مثال استخدام مع TypeScript

import { parse } from 'csv-parse/sync';import { readFileSync } from 'fs';

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

const csvData = readFileSync('users.csv', 'utf-8');const records: User[] = parse(csvData, {    columns: true,          // الصف الأول — العناوين    skip_empty_lines: true,    delimiter: ',',    cast: (value, context) => {        if (context.column === 'id') return parseInt(value, 10);        return value;    }});

console.log(records);

2. PapaParse — محلل عالمي للمتصفح و Node.js

PapaParse — مكتبة ذات دعم ممتاز للملفات الكبيرة (معالجة تدفقية)، واكتشاف تلقائي للفاصل، وإمكانيات تكوين واسعة.

التثبيت

npm install papaparse

مثال مع تحديد أنواع النتائج

import Papa from 'papaparse';

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

const csvString = `sku,price,quantityABC-001,29.99,100ABC-002,49.50,50`;

const result = Papa.parse<Product>(csvString, {    header: true,    dynamicTyping: true,  // تحويل تلقائي للأنواع    skipEmptyLines: true});

if (result.errors.length > 0) {    console.error('أخطاء التحليل:', result.errors);} else {    result.data.forEach(product => {        console.log(`المنتج ${product.sku}: ${product.price} روبل`);    });}

3. csv-stringify — توليد CSV من البيانات

للمهمة العكسية — إنشاء CSV من مصفوفات الكائنات — استخدم csv-stringify. وهو أيضًا جزء من نظام csv.js.

التثبيت

npm install csv-stringify

مثال لتوليد CSV

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

interface Order {    orderId: number;    customer: string;    total: number;}

const orders: Order[] = [    { orderId: 1001, customer: 'إيفان بيتروف', total: 1500.50 },    { orderId: 1002, customer: 'ماريا سيدوروفا', total: 2300.00 },    { orderId: 1003, customer: 'أليكسي إيفانوف', total: 890.75 }];

const csvOutput = stringify(orders, {    header: true,    columns: ['orderId', 'customer', 'total']});

writeFileSync('orders.csv', csvOutput, 'utf-8');console.log('تم إنشاء ملف CSV بنجاح');

4. معالجة الأخطاء والتحقق من صحة البيانات

عند العمل مع CSV، من المهم معالجة الأخطاء بشكل صحيح. لنلق نظرة على مثال مع التحقق من البيانات:

import Papa from 'papaparse';

interface ValidatedRow {    isValid: boolean;    errors: s