Dokumentasi Pengelolaan & Konsumsi @prakarsa-raihan-optima/shared-types

Dokumen ini menjelaskan secara komprehensif bagaimana paket tipe TypeScript bersama (shared-types) dikelola, dibangun, dan dikonsumsi oleh aplikasi klien (Svara, AICON) maupun server backend dalam ekosistem Pro.

1. Arsitektur & Struktur Direktori

Paket shared-types terletak di direktori lokal pro-shared-types dan dirancang sebagai library TypeScript murni yang hanya mengekspor interface dan tipe (tanpa kode runtime atau enum). Hal ini memastikan kompatibilitas yang bersih saat dikompilasi ke berbagai target lingkungan (client/server).

Struktur Sumber Kode (/src)

Di dalam pro-shared-types/src, struktur file diorganisasikan berdasarkan domain fitur:

• index.ts: Entri utama (barrel export) yang mengekspor seluruh tipe untuk konsumsi eksternal.
• shared/: Berisi tipe data global yang digunakan lintas aplikasi (contoh: user.ts).
• svara/: Berisi tipe data khusus untuk aplikasi Svara Training Platform (seperti scenario, recording, dll).
• aicon/: Berisi tipe data khusus untuk aplikasi AICON (seperti ai-provider, prompt-schema, request/response, dll).

2. Proses Build & Kompilasi

Konfigurasi kompilasi diatur melalui file tsconfig.json dengan parameter utama sebagai berikut:

• Target & Module: ES2022 / CommonJS untuk kompatibilitas Node.js backend dan bundler client (Vite).
• Declarations: Menghasilkan file definisi tipe (.d.ts) beserta sourcemap-nya (.d.ts.map) di direktori ./dist.

Skrip Pembangunan

Perintah berikut tersedia di dalam package.json:

# Melakukan kompilasi TypeScript ke folder dist/
npm run build

[!WARNING] Isu Berkas Usang (Stale Files): Compiler TypeScript (tsc) secara bawaan tidak menghapus file di direktori dist/ sebelum melakukan kompilasi ulang. Jika Anda menghapus atau memindahkan file .ts di dalam /src, berkas .d.ts usang mungkin tertinggal di dist/ dan memicu error tipe pada aplikasi konsumen.

Solusi: Selalu bersihkan direktori target sebelum melakukan build ulang:

# Di dalam folder pro-shared-types
rm -rf dist && npm run build

3. Strategi Konsumsi (Local Symlinking)

Paket ini tidak dipublikasikan ke npm registry publik atau privat eksternal. Sebagai gantinya, paket dikonsumsi secara lokal langsung dari folder saudaranya (sibling directory) menggunakan protokol file: di dalam package.json masing-masing aplikasi konsumen.

Konfigurasi Klien & Server

A. Backend Server (pro-ecosystem-server)

Direferensikan di package.json dengan jalur relatif satu tingkat ke atas:

"dependencies": {
  "@prakarsa-raihan-optima/shared-types": "file:../pro-shared-types"
}

B. Svara Training Platform (svara-training-platform)

Direferensikan di package.json dengan jalur relatif satu tingkat ke atas:

"dependencies": {
  "@prakarsa-raihan-optima/shared-types": "file:../pro-shared-types"
}

C. AICON Client (AICON/client)

Direferensikan di package.json with relative path:

"dependencies": {
  "@prakarsa-raihan-optima/shared-types": "file:../../pro-shared-types"
}

4. Alur Kerja Pengembangan (Workflow)

Saat Anda perlu menambahkan atau mengubah tipe data bersama, ikuti langkah-langkah terstandardisasi berikut agar perubahan langsung terdistribusi tanpa merusak tipe di aplikasi konsumen:

graph TD
    A[Edit Tipe Data di pro-shared-types/src] --> B[Jalankan Pembersihan & Build Ulang]
    B --> C[Ulangi Instalasi di Konsumen / npm install]
    C --> D[Gunakan Tipe Baru di Client & Server]
    
    style A fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
    style B fill:#fff9c4,stroke:#fbc02d,stroke-width:2px
    style C fill:#e8f5e9,stroke:#388e3c,stroke-width:2px
    style D fill:#ede7f6,stroke:#7b1fa2,stroke-width:2px

Langkah Detail:

1. Modifikasi Sumber Tipe: Tulis perubahan interface/tipe Anda di bawah folder pro-shared-types/src. Pastikan berkas ekspor terdaftar di file barrel utama (aicon-types.ts / svara-types.ts dan index.ts).

2. Kompilasi Ulang: Lakukan pembersihan folder dist/ dan kompilasi ulang:

   cd c:/Users/leona/OneDrive/apps-by-pro/pro-shared-types
   rm -rf dist
   npm run build

3. Sinkronisasi Node Modules di Konsumen: Karena menggunakan protokol file:, NPM/Yarn membuat symlink di dalam node_modules konsumen ke folder dist milik pro-shared-types. Namun, dalam beberapa kasus bundler/IDE tidak langsung mendeteksi perubahan tipe baru.

   Jika tipe baru tidak terdeteksi oleh VS Code/IDE, jalankan instalasi ulang di direktori konsumen untuk memperbarui link:

   # Di direktori proyek konsumen (contoh: pro-ecosystem-server)
   npm install

4. Penggunaan Kode: Impor tipe seperti paket npm biasa di aplikasi klien atau server:

   import { AIProvider, UserRole } from '@prakarsa-raihan-optima/shared-types';