Sakti Parser FA

Library TypeScript untuk memproses data Laporan Ketersediaan Dana (FA) dari aplikasi Sakti Kementerian Keuangan Republik Indonesia. Mengkonversi file Excel yang tidak terstruktur menjadi data JSON atau CSV yang terorganisir dengan struktur hierarki anggaran yang tepat.

🎯 Deskripsi

Library ini dirancang khusus untuk mem-parsing file Excel laporan FA (Financial Availability) dari sistem Sakti (Sistem Aplikasi Keuangan Tingkat Instansi) Kementerian Keuangan RI. Sistem Sakti menggunakan struktur hierarki anggaran 11 level yang kompleks, dan library ini secara otomatis mengekstrak, memvalidasi, dan mengorganisir data tersebut.

🏛️ Struktur Hierarki Anggaran Sakti

Level 1: Kementerian (145 - KEMENTERIAN KEUANGAN)
├── Level 2: Unit (06 - SEKRETARIAT JENDERAL)
│   ├── Level 3: Satuan Kerja (123456 - BIRO KEUANGAN)
│   │   ├── Level 4: Program (GM - PROGRAM DUKUNGAN MANAJEMEN)
│   │   │   ├── Level 5: Kegiatan (7717 - DUKUNGAN MANAJEMEN KEMENTERIAN)
│   │   │   │   ├── Level 6: Output (CBJ - LAYANAN DUKUNGAN MANAJEMEN)
│   │   │   │   │   ├── Level 7: Sub Output (001 - KOORDINASI DAN SINKRONISASI)
│   │   │   │   │   │   ├── Level 8: Komponen (101 - GAJI DAN TUNJANGAN)
│   │   │   │   │   │   │   ├── Level 9: Sub Komponen (0D - BELANJA PEGAWAI)
│   │   │   │   │   │   │   │   ├── Level 10: Akun (536111 - GAJI POKOK PNS)
│   │   │   │   │   │   │   │   │   └── Level 11: Detail (000052 - BELANJA GAJI POKOK)

✨ Fitur Utama

• 🔄 Parsing Otomatis - Ekstraksi metadata dan data anggaran dari Excel FA
• 🏗️ Struktur Hierarki - Membangun hierarki anggaran 11 level sesuai standar Sakti
• 📊 Multi Format Output - Mendukung Object, JSON, dan CSV
• ✅ Validasi Data - Otomatis validasi dan cleaning data
• 🧮 Agregasi Anggaran - Perhitungan agregasi nilai anggaran secara hierarki
• 🔒 Type Safety - Full TypeScript support dengan type definitions
• 🌐 Bahasa Indonesia - Mendukung parsing tanggal dan teks Indonesia
• ⚡ Performance - Optimized untuk file Excel besar

📦 Instalasi

npm install sakti-parser-fa

🚀 Penggunaan Cepat

Parsing Dasar

import { SaktiParser } from 'sakti-parser-fa';

// Buat instance parser
const parser = new SaktiParser();

// Parse file Excel FA dengan struktur hierarki lengkap
const result = await parser.parseStructuredData('laporan-fa-juli-2025.xlsx');

// Akses metadata
console.log('Kementerian:', result.metadata.kementerian_nama);
console.log('Periode:', result.metadata.periode_text);
console.log('Satuan Kerja:', result.metadata.satuan_kerja_nama);

// Akses data anggaran
result.data.forEach(item => {
  console.log(`Level ${item._level}: ${item.uraian}`);
  console.log(`Pagu: Rp ${item.pagu.toLocaleString('id-ID')}`);
  console.log(`Realisasi: ${(item.realisasi_persen * 100).toFixed(2)}%`);
});

Export ke Format Lain

// Export ke CSV
const parser = new SaktiParser({
  outputFormat: 'csv',
  csvOptions: {
    delimiter: ';',
    header: true
  }
});

const csvResult = await parser.parseAndFormat('laporan-fa.xlsx');
console.log(csvResult.content.data); // String CSV

// Export ke JSON
const jsonParser = new SaktiParser({ outputFormat: 'json' });
const jsonResult = await jsonParser.parseAndFormat('laporan-fa.xlsx');
console.log(jsonResult.content); // JSON string

Analisis Data

const result = await parser.parseStructuredData('laporan-fa.xlsx');

// Filter program utama (level 4)
const programs = result.data.filter(item => item._level === 4);

// Hitung total anggaran
const totalBudget = result.data
  .filter(item => item._level === 11) // Level detail
  .reduce((sum, item) => sum + item.pagu, 0);

// Analisis realisasi
const lowRealization = result.data.filter(item => 
  item._level === 11 && 
  item.pagu > 100000000 && // > 100 juta
  item.realisasi_persen < 0.2 // < 20%
);

console.log(`Total Anggaran: Rp ${totalBudget.toLocaleString('id-ID')}`);
console.log(`Program dengan realisasi rendah: ${lowRealization.length}`);

📊 Format Data

Input: File Excel FA

Library mengharapkan file Excel dengan struktur:

• Baris 1: Judul laporan
• Baris 3: Periode (contoh: "Periode Juli 2025")
• Baris 4-6: Metadata kementerian, unit, satuan kerja
• Baris 10+: Data anggaran hierarki

Output: Data Terstruktur

interface ParseResult {
  metadata: {
    judul: string;
    periode_text: string;
    periode_bulan: number;
    periode_tahun: number;
    kementerian_kode: string;
    kementerian_nama: string;
    unit_kode: string;
    unit_nama: string;
    satuan_kerja_kode: string;
    satuan_kerja_nama: string;
  };
  data: Array<{
    _level: number;                   // Level hierarki (1-11)
    _parent: string;                  // Mata anggaran parent
    mata_anggaran: string;            // Kode mata anggaran lengkap
    kode: string;                     // Kode item
    uraian: string;                   // Deskripsi
    pagu: number;                     // Anggaran (Rupiah)
    pagu_terkunci: number;            // Anggaran terkunci
    realisasi_sebelum: number;        // Realisasi periode sebelumnya
    realisasi_periode: number;        // Realisasi periode ini
    realisasi_kumulatif: number;      // Total realisasi
    realisasi_persen: number;         // Persentase realisasi (0.0-1.0)
    sisa_anggaran: number;            // Sisa anggaran
  }>;
}

🔧 Konfigurasi

const parser = new SaktiParser({
  outputFormat: 'csv',           // 'object' | 'json' | 'csv'
  csvOptions: {
    delimiter: ';',              // Pemisah kolom
    header: true,                // Include header
    quoted: true                 // Quote semua field
  },
  jsonOptions: {
    flat: true                   // Array flat vs nested object
  }
});

📚 Dokumentasi

• 📖 Panduan Cepat - Tutorial step-by-step
• 📋 API Reference - Dokumentasi lengkap API
• 💡 Contoh Penggunaan - 12+ contoh real-world
• 📊 Format Data - Struktur input dan output
• 🔧 Troubleshooting - Pemecahan masalah
• 🤝 Contributing - Panduan kontribusi

🧪 Testing

# Jalankan semua test
npm test

# Test dengan coverage
npm run test:coverage

# Watch mode untuk development
npm run test:watch

Coverage: 85%+ dengan 28 test cases mencakup edge cases dan error handling.

🛠️ Development

# Clone repository
git clone https://github.com/username/sakti-parser-fa.git
cd sakti-parser-fa

# Install dependencies
npm ci

# Build library
npm run build

# Format code
npm run format

# Lint code
npm run lint

# Check semua (lint + build)
npm run check

⚙️ Requirements

• Node.js >= 18.0.0
• npm >= 8.0.0

🔄 Changelog

Lihat CHANGELOG.md untuk riwayat perubahan lengkap.

Versi Terbaru: 0.6.1

• ✅ Dokumentasi lengkap dalam Bahasa Indonesia
• ✅ README.md professional dengan visual hierarki Sakti
• ✅ 12+ contoh penggunaan real-world
• ✅ API reference dan troubleshooting guide
• ✅ Panduan kontribusi untuk developer

🤝 Contributing

Kami sangat menghargai kontribusi! Silakan baca panduan kontribusi untuk detail lengkap.

Quick Start Contributing:

1. Fork repository
2. Buat branch: git checkout -b feature/nama-fitur
3. Commit: git commit -m 'Add amazing feature'
4. Push: git push origin feature/nama-fitur
5. Submit pull request

📄 License

MIT License - lihat LICENSE untuk detail lengkap.

🏷️ Keywords

sakti kementerian-keuangan anggaran excel-parser typescript indonesia government budget financial-data hierarchical-data

🆘 Support

Butuh bantuan?

1. 📖 Cek dokumentasi di folder docs
2. 🔍 Search issues di GitHub Issues
3. 💬 Diskusi di GitHub Discussions
4. 🐛 Laporkan bug dengan template yang disediakan

📈 Stats

• ⭐ GitHub Stars:
• 📦 NPM Downloads:
• 🔧 TypeScript: 100%
• 🧪 Test Coverage: 85%+
• 📚 Documentation: Bahasa Indonesia