type: component-spec
version: 1.0.0
component: Index Manager
module: engine
status: Draft
created: 2026-06-11
author: opencode
🎯 Specyfikacja Komponentu: Index Manager
[!ABSTRACT] Epigraf
"Zarządza metadanymi baz danych i tabel — indeksowanie, szybki lookup, statystyki. Operuje na plikach .meta.json."
| Pole | Wartość |
|---|
| Nazwa | Index Manager |
| Moduł | src/engine/index-manager.ts |
| Wersja | 1.0.0 |
| Status | Draft |
| Zależny od | — |
| Używany przez | Database Tools, Table Tools, CRUD Tools |
§2. 🎯 Cel i Odpowiedzialność
§2.1 Cel
Zapewnienie szybkiego dostępu do metadanych baz i tabel bez konieczności skanowania całego katalogu danych. Prowadzi indeks w plikach .meta.json.
§2.2 Odpowiedzialności
- Tworzenie i aktualizacja
.meta.json na poziomie bazy
- Listowanie wszystkich baz danych
- Listowanie tabel w bazie
- Statystyki: liczba tabel, łączny rozmiar, data ostatniej modyfikacji
- Quick lookup: sprawdzenie czy baza/tabela istnieje (O(1))
- Cache w pamięci dla często używanych indeksów
§3. 🛠️ Specyfikacja API/Funkcji
§3.1 Funkcja: getDatabases(): Promise<DatabaseInfo[]>
- Opis: Skanuje
data-root/databases/ i zwraca listę baz z danymi z .meta.json.
- Rzuca:
FilesystemError jeśli data-root nie istnieje
§3.2 Funkcja: getTables(database: string): Promise<TableInfo[]>
- Opis: Zwraca listę tabel w bazie wraz z metadanymi.
- Rzuca:
NotFoundError jeśli baza nie istnieje
§3.3 Funkcja: getIndex(database: string): Promise<DatabaseIndex>
- Opis: Ładuje
.meta.json dla bazy.
§3.4 Funkcja: updateIndex(database: string, updates: Partial<DatabaseIndex>): Promise<void>
- Opis: Aktualizuje
.meta.json — np. po dodaniu/usunięciu tabeli.
§3.5 Funkcja: initDatabase(name: string): Promise<void>
- Opis: Tworzy katalog bazy + inicjalizuje
.meta.json.
- Rzuca:
DuplicateError jeśli baza już istnieje
§3.6 Funkcja: deleteDatabase(name: string): Promise<void>
- Opis: Usuwa katalog bazy wraz z całym indeksem.
§3.7 Funkcja: databaseExists(name: string): Promise<boolean>
- Opis: Sprawdza czy baza istnieje (O(1) z cache).
§3.8 Funkcja: tableExists(database: string, table: string): Promise<boolean>
- Opis: Sprawdza czy tabela istnieje.
§3.9 Parametry
| Parametr | Typ | Opis |
|---|
database | string | Nazwa bazy (identyfikator) |
table | string | Nazwa tabeli (identyfikator) |
name | string | Nazwa do inicjalizacji |
updates | Partial<DatabaseIndex> | Częściowa aktualizacja indeksu |
§3.10 Zwraca
| Funkcja | Zwraca |
|---|
getDatabases | Promise<DatabaseInfo[]> |
getTables | Promise<TableInfo[]> |
getIndex | Promise<DatabaseIndex> |
updateIndex | Promise<void> |
initDatabase | Promise<void> |
deleteDatabase | Promise<void> |
databaseExists | Promise<boolean> |
tableExists | Promise<boolean> |
§4. 🏗️ Struktura Danych
§5. 🔗 Zależności
§5.1 Wewnętrzne
- Brak autonomicznych — operuje bezpośrednio na FS
§5.2 Zewnętrzne
| Biblioteka | Wersja | Użycie |
|---|
path | (Node.js) | Manipulacje ścieżkami |
fs/promises | (Node.js) | Odczyt/zapis plików |
§6. 💻 Przykładowe Użycie
Scenariusze użycia
| Scenariusz | Wywołanie | Rezultat |
|---|
| Inicjalizacja bazy | initDatabase("x") | Tworzy katalog + .meta.json |
| Listowanie po dodaniu tabeli | updateIndex("x", { tables: {...} }) | Aktualizuje .meta.json |
| Usunięcie bazy | deleteDatabase("x") | Usuwa katalog |
| Sprawdzenie przed create | databaseExists("x") | true / false |
§7. Stany i Cykl Życia
§8. Obsługa Błędów
| Błąd | Kod | Przyczyna | Recovery |
|---|
NotFoundError | DB_NOT_FOUND | Baza nie istnieje | Zwróć błąd do narzędzia |
DuplicateError | DUPLICATE_DATABASE | Próba stworzenia istniejącej bazy | Zwróć info do LLM |
FilesystemError | FILESYSTEM_ERROR | Brak dostępu do data-root | Retry 2x |
§9. 🧪 Testy
Jednostkowe
| Given | When | Then |
|---|
| Data-root z 2 bazami | getDatabases() | Zwraca tablicę 2 DatabaseInfo |
| Pusty data-root | getDatabases() | Zwraca pustą tablicę [] |
| Nieistniejąca baza | getTables("nonexistent") | Rzuca NotFoundError |
| Init nowej bazy | initDatabase("test") | Tworzy katalog + .meta.json |
| Init istniejącej bazy | initDatabase("test") (2x) | Rzuca DuplicateError |
| Sprawdzenie istniejącej bazy | databaseExists("test") | true |
| Sprawdzenie nieistniejącej bazy | databaseExists("nope") | false |
Mocki / Fixtures
- Tymczasowy katalog
tmp/data/databases/ z 1-2 bazami
- Przykładowy
.meta.json z 2 tabelami
§10. Powiązane Dokumenty
- TDD:
../../TDD.md — §5.1 Index Manager API
- Database Tools:
database-tools.md — wywołuje initDatabase, deleteDatabase
- CSV Engine:
csv-engine.md — aktualizuje indeks po zapisie