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

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

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

المكتبات الشائعة للعمل مع CSV

المكتبات الأكثر استخدامًا في بيئة TypeScript/Node.js:

• csv-parse — جزء من مجموعة csv، محلل موثوق مع دعم التدفقات
• papaparse — محلل متعدد الاستخدامات للمتصفح و Node.js
• csv-stringify — مولد CSV من المصفوفات/الكائنات
• csvtojson — محول CSV إلى JSON مع كتابة الأنواع

التثبيت والإعداد

للمشاريع المكتوبة بـ TypeScript، يتم التثبيت عبر npm أو yarn:

npm install csv-parse csv-stringify papaparse @types/papaparse

إذا كنت تستخدم csv-parse، فلا حاجة لأنواع إضافية — المكتبة تحتوي على دعم مدمج لـ TypeScript.

مثال 1: تحليل CSV باستخدام csv-parse

مكتبة csv-parse مناسبة تمامًا للعمل مع الملفات الكبيرة بفضل واجهة التدفق (stream API). لنلقِ نظرة على مثال أساسي:

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

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

const csvData = fs.readFileSync('users.csv', 'utf-8');

const records: User[] = parse(csvData, {  columns: true,       // السطر الأول هو الرؤوس  skip_empty_lines: true,  delimiter: ',',  cast: (value, context) => {    if (context.column === 'id' || context.column === 'age') {      return Number(value);    }    return value;  }});

console.log(records);// [//   { id: 1, name: 'إيفان', email: 'ivan@example.com', age: 30 },//   { id: 2, name: 'ماريا', email: 'maria@example.com', age: 25 }// ]

مثال 2: إنشاء CSV مع كتابة الأنواع

لإنشاء ملفات CSV، استخدم csv-stringify. دعنا نحدد نوع البيانات وننشئ سلسلة نصية:

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

interface Product {  productId: string;  name: string;  price: number;  inStock: boolean;}

const products: Product[] = [  { productId: 'P001', name: 'لابتوب', price: 75000, inStock: true },  { productId: 'P002', name: 'فأرة', price: 1500, inStock: false },  { productId: 'P003', name: 'لوحة مفاتيح', price: 3500, inStock: true }];

const csvOutput = stringify(products, {  header: true,  columns: ['productId', 'name', 'price', 'inStock']});

console.log(csvOutput);// productId,name,price,inStock// P001,لابتوب,75000,true// P002,فأرة,1500,false// P003,لوحة مفاتيح,3500,true

مثال 3: استخدام PapaParse في المتصفح

PapaParse مثالي لمعالجة CSV من جانب العميل. مثال مع تحميل ملف عبر input:

import Papa from 'papaparse';

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

const fileInput = document.getElementById('csvInput') as HTMLInputElement;

fileInput.addEventListener('change', (event) => {  const file = (event.target as HTMLInputElement).files?.[0];  if (!file) return;

  Papa.parse<Transaction>(file, {    header: true,    dynamicTyping: true,  // تحويل تلقائي للأنواع    skipEmptyLines: true,    complete: (result) => {      console.log('اكتمل التحليل:', result.data);      // result.data — مصفوفة من كائنات Transaction    },    error: (error) => {      console.error('خطأ في التحليل:', error);    }  });});

مثال 4: