type: component-spec
version: 1.0.0
component: CSV Engine
module: engine
status: Draft
created: 2026-06-11
author: opencode 🎯 Specyfikacja Komponentu: CSV Engine
[!ABSTRACT] Epigraf
"Silnik CSV odpowiedzialny za parsowanie, generowanie, append i edycję plików CSV. Stanowi warstwę dostępu do danych dla wszystkich narzędzi."
Pole Wartość Nazwa CSV Engine Moduł src/engine/csv-engine.tsWersja 1.0.0 Status Draft Zależny od Schema Manager, Index Manager Używany przez Database Tools, Table Tools, CRUD Tools, Query Tools
§2. 🎯 Cel i Odpowiedzialność §2.1 Cel Zapewnienie niezawodnych operacji odczytu/zapisu na plikach CSV z obsługą BOM, quoting/escaping, dużych plików i współbieżności.
§2.2 Odpowiedzialności
Parsowanie plików CSV do Record<string, any>[]
Generowanie stringa CSV z nagłówkami i quotingiem
Dopisywanie wierszy do istniejących plików CSV (append)
Nadpisywanie całego pliku CSV (write)
Wykrywanie i obsługa BOM (UTF-8) dla zgodności z Excel
Walidacja struktury pliku przed operacjami
§3. 🛠️ Specyfikacja API/Funkcji §3.1 Funkcja: parseCSV(path: string): Promise<Record<string, any>[]>
Opis : Parsuje plik CSV do tablicy obiektów. Pierwszy wiersz = nagłówki.Rzuca : FilesystemError jeśli plik nie istnieje, CSVParseError jeśli format jest niepoprawny
§3.2 Funkcja: stringifyCSV(rows: Record<string, any>[], columns: ColumnDef[]): Promise<string>
Opis : Generuje string CSV z nagłówkami (nazwy kolumn) i danymi. Stosuje proper quoting/escaping.Rzuca : ValidationError jeśli wiersze nie zgadzają się z kolumnami
§3.3 Funkcja: appendToCSV(path: string, row: Record<string, any>): Promise<void>
Opis : Dopisuje jeden wiersz na końcu pliku CSV. Jeśli plik nie istnieje — tworzy go z nagłówkami.Rzuca : FilesystemError przy błędzie I/O
§3.4 Funkcja: appendRowsToCSV(path: string, rows: Record<string, any>[]): Promise<void>
Opis : Batch append wielu wierszy — jeden zapis zamiast N.
§3.5 Funkcja: writeCSV(path: string, rows: Record<string, any>[], columns: ColumnDef[]): Promise<void>
Opis : Nadpisuje cały plik CSV od nowa.
Opis : Odczytuje tylko nagłówki (pierwszy wiersz) z CSV — szybki lookup bez pełnego parsowania.
§3.7 Parametry Parametr Typ Opis pathstringBezwzględna ścieżka do pliku .csv rowRecord<string, any>Pojedynczy wiersz danych rowsRecord<string, any>[]Tablica wierszy columnsColumnDef[]Definicje kolumn (nazwa, typ)
§3.8 Zwraca Funkcja Zwraca parseCSVPromise<Record<string, any>[]>stringifyCSVPromise<string>appendToCSVPromise<void>appendRowsToCSVPromise<void>writeCSVPromise<void>readCSVHeadersPromise<string[]>
§4. 🏗️ Struktura Danych
§5. 🔗 Zależności §5.1 Wewnętrzne
./schema — ColumnDef, validateRowAgainstSchema do walidacji typów przed zapisem./index-manager — aktualizacja .meta.json po modyfikacji
§5.2 Zewnętrzne Biblioteka Wersja Użycie csv-parse^5.x Parsowanie CSV z wykrywaniem nagłówków csv-stringify^6.x Generowanie CSV z proper quoting/escaping path(Node.js) Manipulacje ścieżkami fs/promises(Node.js) Operacje I/O
§6. 💻 Przykładowe Użycie
Scenariusze użycia Scenariusz Wywołanie Rezultat Nowa tabela (pierwszy wiersz) appendToCSV(path, row)Tworzy plik z nagłówkami + 1 wiersz Dopisanie rekordu appendToCSV(path, row)Dopisuje wiersz na końcu Batch import 1000 wierszy appendRowsToCSV(path, rows)Jeden zapis, 1000 wierszy Nadpisanie całej tabeli writeCSV(path, rows, columns)Całkowita regeneracja pliku
§7. Stany i Cykl Życia
§8. Obsługa Błędów Błąd Kod Przyczyna Recovery CSVParseErrorCSV_PARSE_ERRORUszkodzony CSV, nieprawidłowe quoting Zwróć błąd z numerem linii FilesystemErrorFILESYSTEM_ERRORBrak dostępu, brak miejsca na dysku Retry 2x, potem błąd ValidationErrorVALIDATION_ERRORNiezgodność typów/wymaganych pól Rzuć z listą konkretnych błędów
§9. 🧪 Testy Jednostkowe Given When Then Poprawny CSV z 3 kolumnami i 2 wierszami parseCSV(path)Zwraca tablicę 2 obiektów z kluczami z nagłówków Pusty plik CSV (tylko nagłówki) parseCSV(path)Zwraca pustą tablicę [] CSV z BOM parseCSV(path)Ignoruje BOM, poprawnie parsuje Wiersz z przecinkami w stringu stringifyCSV(rows, cols)Poprawnie quotuje pole Nieistniejący plik parseCSV(path)Rzuca FilesystemError Batch 1000 wierszy appendRowsToCSV(path, rows)Jeden zapis do pliku, wszystkie wiersze
Mocki / Fixtures
test/fixtures/simple.csv — 3 kolumny, 2 wierszetest/fixtures/empty.csv — tylko nagłówkitest/fixtures/bom.csv — CSV z BOMtest/fixtures/complex.csv — stringi z przecinkami, cudzysłowami, newlinami
§10. Powiązane Dokumenty
TDD : ../../TDD.md — §4 CSV Engine, §5 Interface DefinitionsSchema Manager : schema-manager.md — typy kolumn, walidacjaIndex Manager : index-manager.md — aktualizacja metadanych po zapisie