lapeh 2.4.6 → 2.4.7

package/doc/id/CHEATSHEET.md

@@ -0,0 +1,94 @@
+# Lapeh Framework Cheatsheet
+
+Referensi cepat untuk perintah dan kode yang sering digunakan.
+
+## 💻 CLI Commands
+
+| Perintah                             | Fungsi                                       |
+| :----------------------------------- | :------------------------------------------- |
+| **`npm run dev`**                    | Menjalankan server development (hot-reload). |
+| **`npm run typecheck`**              | Cek error TypeScript (tanpa compile).        |
+| **`npm run lint`**                   | Cek kode kotor/variabel tidak terpakai.      |
+| **`npm run lint:fix`**               | Perbaiki kode kotor otomatis.                |
+| **`npm run make:module <Name>`**     | Buat Controller, Route, & Model sekaligus.   |
+| **`npm run make:controller <Name>`** | Buat Controller saja.                        |
+| **`npm run make:model <Name>`**      | Buat Model Prisma saja.                      |
+| **`npm run prisma:migrate`**         | Apply perubahan schema ke DB lokal.          |
+| **`npm run db:studio`**              | Buka GUI Database.                           |
+| **`npm run db:seed`**                | Isi data dummy.                              |
+| **`npm run db:reset`**               | Hapus DB & mulai dari nol.                   |
+
+## 🛡️ Validator Rules (Laravel-Style)
+
+Gunakan di `Validator.make(data, rules)`.
+
+| Rule               | Deskripsi               | Contoh                              |
+| :----------------- | :---------------------- | :---------------------------------- | -------- |
+| `required`         | Wajib ada & tidak null. | `"required"`                        |
+| `string`           | Harus text.             | `"required                          | string"` |
+| `number`           | Harus angka.            | `"required                          | number"` |
+| `email`            | Format email valid.     | `"required                          | email"`  |
+| `min:X`            | Min panjang/nilai.      | `"min:8"` (pass), `"min:18"` (umur) |
+| `max:X`            | Max panjang/nilai.      | `"max:255"`                         |
+| `unique:table,col` | Cek unik di DB.         | `"unique:users,email"`              |
+| `exists:table,col` | Cek exist di DB.        | `"exists:roles,id"`                 |
+| `image`            | File harus gambar.      | `"required                          | image"`  |
+| `mimes:types`      | File extension.         | `"mimes:pdf,docx"`                  |
+
+## 🔑 Authentication
+
+**Middleware di Route:**
+
+```typescript
+import { requireAuth, requireAdmin } from "@/middleware/auth";
+
+router.get("/profile", requireAuth, getProfile); // Login User
+router.delete("/user", requireAuth, requireAdmin, del); // Admin Only
+```
+
+**Akses User di Controller:**
+
+```typescript
+// (req as any).user tersedia setelah requireAuth
+const userId = (req as any).user.userId;
+const role = (req as any).user.role;
+```
+
+## ⚡ Fast Response (Serializer)
+
+**1. Schema:**
+
+```typescript
+const schema = {
+  type: "object",
+  properties: {
+    id: { type: "string" },
+    name: { type: "string" },
+  },
+};
+```
+
+**2. Serializer:**
+
+```typescript
+const serializer = getSerializer("key-name", createResponseSchema(schema));
+```
+
+**3. Send:**
+
+```typescript
+sendFastSuccess(res, 200, serializer, { ...data });
+```
+
+## 📦 Redis (Cache)
+
+```typescript
+import { redis } from "@lapeh/core/redis";
+
+// Set Cache (Key, Value, Mode, Detik)
+await redis.set("profile:1", JSON.stringify(data), "EX", 3600);
+
+// Get Cache
+const cached = await redis.get("profile:1");
+if (cached) return JSON.parse(cached);
+```

package/doc/id/CONTRIBUTING.md

@@ -0,0 +1,105 @@
+# Panduan Kontribusi (Contributing Guide)
+
+Terima kasih atas ketertarikan Anda untuk berkontribusi pada pengembangan **Lapeh Framework**! 🎉
+
+Proyek ini bersifat **Open Source** dan kami sangat menghargai setiap bentuk kontribusi, baik itu perbaikan bug, penambahan fitur, dokumentasi, maupun sekadar laporan error (issue).
+
+Dokumen ini akan memandu Anda tentang cara berkontribusi dengan benar dan efisien.
+
+## 🚀 Memulai Kontribusi
+
+### 1. Persiapan Lingkungan (Prerequisites)
+Pastikan Anda sudah menginstal:
+- **Node.js** (v18 ke atas)
+- **Git**
+- **Code Editor** (VS Code disarankan, dengan ekstensi ESLint & Prettier)
+
+### 2. Fork & Clone Repository
+1.  **Fork** repository ini ke akun GitHub Anda (tombol "Fork" di pojok kanan atas).
+2.  **Clone** hasil fork ke komputer lokal Anda:
+    ```bash
+    git clone https://github.com/USERNAME_ANDA/lapeh.git
+    cd lapeh
+    ```
+3.  **Tambahkan Remote Upstream** (agar bisa sinkron dengan repo asli):
+    ```bash
+    git remote add upstream https://github.com/robyajo/lapeh.git
+    ```
+
+### 3. Instalasi Dependencies
+```bash
+npm install
+```
+Jangan lupa jalankan setup awal untuk database lokal (pastikan PostgreSQL/MySQL jalan):
+```bash
+cp .env.example .env
+npm run prisma:migrate
+npm run db:seed
+```
+
+## 🛠️ Workflow Pengembangan
+
+### 1. Buat Branch Baru
+Jangan bekerja langsung di branch `main`. Buat branch baru yang deskriptif:
+```bash
+git checkout -b feature/tambah-validasi-email
+# atau
+git checkout -b fix/typo-dokumentasi
+```
+
+### 2. Standar Koding (Coding Standards)
+Kami menerapkan aturan yang ketat demi menjaga kualitas kode.
+- **TypeScript**: Gunakan tipe data eksplisit. Hindari `any` sebisa mungkin.
+- **Linter**: Pastikan tidak ada error ESLint. Variabel tidak terpakai harus dihapus atau diberi prefix `_`.
+- **Formatter**: Kode harus rapi.
+
+Sebelum commit, **WAJIB** jalankan perintah ini untuk memastikan kode Anda bersih:
+```bash
+npm run typecheck  # Cek error TypeScript
+npm run lint       # Cek error Linter
+```
+
+### 3. Commit Message Convention
+Gunakan format **Conventional Commits** agar history mudah dibaca:
+- `feat: ...` untuk fitur baru.
+- `fix: ...` untuk perbaikan bug.
+- `docs: ...` untuk perubahan dokumentasi.
+- `chore: ...` untuk perubahan kecil (config, script).
+- `refactor: ...` untuk perbaikan struktur kode tanpa mengubah fitur.
+
+**Contoh:**
+```text
+feat: add email validation rule to validator
+fix: resolve EADDRINUSE error on windows
+docs: update installation guide
+```
+
+## 📮 Mengirim Pull Request (PR)
+
+1.  **Push** branch Anda ke GitHub:
+    ```bash
+    git push origin feature/nama-fitur
+    ```
+2.  Buka repository fork Anda di GitHub, lalu klik **Compare & pull request**.
+3.  Isi judul dan deskripsi PR dengan jelas:
+    - Jelaskan apa yang Anda ubah.
+    - Sertakan screenshot (jika ada perubahan visual/output).
+    - Referensikan Issue jika ada (contoh: `Closes #123`).
+4.  Tunggu review dari maintainer. Kami mungkin akan meminta revisi kecil.
+5.  Setelah disetujui, kode Anda akan di-merge! 🚀
+
+## 🐛 Melaporkan Bug (Issues)
+
+Jika Anda menemukan bug tapi belum bisa memperbaikinya, silakan buat **Issue** baru.
+- Gunakan judul yang jelas.
+- Jelaskan langkah-langkah untuk mereproduksi bug (Steps to Reproduce).
+- Sertakan log error atau screenshot.
+- Sebutkan versi Node.js dan OS yang digunakan.
+
+## 💡 Ide & Diskusi
+
+Punya ide fitur baru? Jangan ragu untuk membukanya di **GitHub Discussions** atau buat Issue dengan label `enhancement` sebelum mulai koding, agar kita bisa mendiskusikan desainnya terlebih dahulu.
+
+---
+
+Selamat berkontribusi! Kode Anda akan membantu developer lain membangun aplikasi dengan lebih cepat dan menyenangkan. ❤️

package/doc/id/DEPLOYMENT.md

@@ -0,0 +1,245 @@
+# Deployment Guide
+
+Panduan ini akan membantu Anda membawa aplikasi Lapeh dari `localhost` ke Server Production (VPS/Cloud).
+
+## Persiapan Pra-Deploy
+
+Sebelum deploy, pastikan:
+
+1.  **Environment Variables**: Siapkan nilai `.env` untuk production (DB URL asli, JWT Secret yang kuat).
+2.  **Build**: TypeScript harus dikompilasi ke JavaScript.
+
+## Strategi 1: VPS (Ubuntu/Debian) dengan PM2
+
+Ini adalah cara paling umum dan hemat biaya.
+
+### 1. Setup Server
+
+Pastikan Node.js, NPM, dan Database (PostgreSQL/MySQL) sudah terinstall di server.
+
+### 2. Clone & Install
+
+```bash
+git clone https://github.com/username/repo-anda.git
+cd repo-anda
+npm install --production=false # Install devDependencies juga untuk build
+```
+
+### 3. Build Aplikasi
+
+```bash
+npm run build
+```
+
+Ini akan menghasilkan folder `dist/`.
+
+### 4. Setup Database Production
+
+```bash
+# Setup .env dulu
+cp .env.example .env
+nano .env # Isi dengan config production
+
+# Jalankan migrasi (Hanya deploy schema, jangan reset!)
+npm run prisma:deploy
+```
+
+### 5. Jalankan dengan PM2
+
+Lapeh kini menyertakan konfigurasi otomatis PM2 (`ecosystem.config.js`).
+
+1.  **Install PM2 Global**:
+
+    ```bash
+    npm install -g pm2
+    ```
+
+2.  **Jalankan Aplikasi**:
+
+    ```bash
+    pm2 start ecosystem.config.js
+    ```
+
+    Perintah ini akan:
+
+    - Menjalankan aplikasi dalam mode **Cluster** (menggunakan semua core CPU yang tersedia).
+    - Mengatur `NODE_ENV` ke `production`.
+    - Mengaktifkan auto-restart jika aplikasi crash atau penggunaan memori melebihi 1GB.
+
+3.  **Cek Status**:
+
+    ```bash
+    pm2 status
+    pm2 logs
+    ```
+
+4.  **Simpan Config Startup (Agar jalan saat server reboot)**:
+    ```bash
+    pm2 save
+    pm2 startup
+    ```
+
+### ❓ FAQ: Mengapa Aplikasi Saya Muncul Ganda di PM2?
+
+Jika Anda menjalankan `pm2 list` dan melihat nama aplikasi Anda muncul lebih dari satu kali (misal: `my-app` ada 2 atau 4 baris), **JANGAN KHAWATIR**. Ini adalah fitur, bukan bug.
+
+- **Penyebab**: Konfigurasi `instances: "max"` dan `exec_mode: "cluster"` di `ecosystem.config.js`.
+- **Fungsi**: PM2 mendeteksi jumlah inti CPU (Core) di VPS Anda dan membuat 1 proses worker untuk setiap core.
+  - Jika VPS punya 2 vCPU -> Muncul 2 proses.
+  - Jika VPS punya 4 vCPU -> Muncul 4 proses.
+- **Keuntungan**: Aplikasi Anda menjadi **Multi-Threaded**. Request yang masuk akan dibagi rata ke semua proses, meningkatkan performa 2x-4x lipat dibanding mode biasa.
+
+**Cara mengubah ke Single Instance (Hemat RAM):**
+Jika RAM server Anda terbatas (misal 512MB/1GB) dan ingin menghemat resource, ubah `ecosystem.config.js`:
+
+```javascript
+module.exports = {
+  apps: [
+    {
+      name: "my-app",
+      // ...
+      instances: 1, // Ubah "max" menjadi 1
+      // ...
+    },
+  ],
+};
+```
+
+Lalu jalankan `pm2 reload ecosystem.config.js`.
+
+### 7. Advanced: Menjalankan Beberapa Aplikasi (Multi-App)
+
+Jika Anda memiliki beberapa aplikasi Node.js dalam satu VPS (misalnya: Backend API, Frontend React SSR, dan API Lapeh), Anda bisa menggabungkannya dalam satu file `ecosystem.config.js`.
+
+Berikut adalah contoh konfigurasi **Real World** untuk menjalankan 3 aplikasi sekaligus:
+
+```javascript
+module.exports = {
+  apps: [
+    // 1. APLIKASI LAIN (Contoh: Backend MERN)
+    {
+      name: "api-mern-news",
+      cwd: "/var/www/html/node/api-mern-news",
+      script: "dist/src/index.js",
+      env: {
+        NODE_ENV: "production",
+        PORT: 4000,
+      },
+    },
+
+    // 2. APLIKASI LAIN (Contoh: Frontend React/Next.js)
+    {
+      name: "web-mern-news",
+      cwd: "/var/www/html/node/web-mern-news",
+      script: "npm",
+      args: "start", // Menjalankan 'npm start'
+      env: {
+        NODE_ENV: "production",
+        PORT: 3001,
+      },
+    },
+
+    // 3. APLIKASI LAPEH FRAMEWORK
+    {
+      name: "api-lapeh-project",
+      cwd: "/var/www/html/node/my-lapeh-project",
+
+      // PENTING: Gunakan binary Lapeh dari node_modules lokal
+      script: "./node_modules/lapeh/bin/index.js",
+
+      // Argument 'start' untuk mode produksi
+      args: "start",
+
+      // Mode Cluster (Gunakan semua Core CPU)
+      instances: "max",
+      exec_mode: "cluster",
+
+      // Restart jika memori bocor > 1GB
+      max_memory_restart: "1G",
+
+      // Matikan watch di production
+      watch: false,
+
+      env: {
+        NODE_ENV: "production",
+        PORT: 8001,
+      },
+    },
+  ],
+};
+```
+
+**Tips:**
+
+1.  Sesuaikan `cwd` (Current Working Directory) dengan lokasi folder proyek Anda di VPS.
+2.  Pastikan port tidak bentrok antar aplikasi (contoh di atas: 4000, 3001, 8001).
+3.  Simpan file ini di root folder proyek utama atau di folder khusus konfigurasi server Anda.
+4.  Jalankan semua aplikasi sekaligus dengan: `pm2 start ecosystem.config.js`.
+
+### 8. Reverse Proxy (Nginx)
+
+Jangan expose port 4000 langsung. Gunakan Nginx di depannya.
+Config Nginx block:
+
+```nginx
+server {
+    server_name api.domain-anda.com;
+    location / {
+        proxy_pass http://localhost:4000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_cache_bypass $http_upgrade;
+    }
+}
+```
+
+## Strategi 2: Docker (Container)
+
+Lapeh sudah menyertakan `Dockerfile` (jika belum, buat sederhana saja).
+
+**Dockerfile Minimal:**
+
+```dockerfile
+FROM node:18-alpine
+
+WORKDIR /app
+
+COPY package*.json ./
+RUN npm install
+
+COPY . .
+RUN npm run build
+
+EXPOSE 4000
+CMD ["npm", "run", "start:prod"]
+```
+
+**Deploy:**
+
+```bash
+docker build -t my-lapeh-app .
+docker run -p 4000:4000 --env-file .env my-lapeh-app
+```
+
+## Strategi 3: PaaS (Railway / Render / Vercel)
+
+Platform seperti Railway.app sangat mudah karena mendeteksi `package.json`.
+
+1.  Push kode ke GitHub.
+2.  Connect repo di Railway/Render.
+3.  Set Environment Variables di dashboard mereka.
+4.  Set **Build Command**: `npm run build`.
+5.  Set **Start Command**: `npm run start:prod`.
+
+**Catatan Khusus Vercel (Serverless):**
+Lapeh didesain sebagai _Long-Running Server_ (Express). Deploy ke Vercel dimungkinkan tapi butuh wrapper serverless (seperti `vercel-express`). Untuk performa terbaik, disarankan menggunakan VPS atau Container (Railway/Fly.io).
+
+## Checklist Keamanan Production
+
+- [ ] `NODE_ENV=production` harus diset.
+- [ ] `JWT_SECRET` harus panjang dan acak.
+- [ ] Database tidak boleh terekspos ke publik (gunakan private network atau firewall).
+- [ ] Rate Limiting aktif (default Lapeh sudah aktif).
+- [ ] Gunakan HTTPS (SSL) via Nginx atau Cloudflare.

package/doc/id/FAQ.md

@@ -0,0 +1,81 @@
+# Frequently Asked Questions (FAQ)
+
+Kumpulan pertanyaan umum dan solusi untuk masalah yang sering dihadapi.
+
+## Database
+
+### Q: Bagaimana cara mengganti database dari PostgreSQL ke MySQL?
+**A:**
+1. Buka `prisma/base.prisma.template`.
+2. Ubah `provider = "postgresql"` menjadi `provider = "mysql"`.
+3. Di `.env`, ubah `DATABASE_URL` formatnya menjadi format MySQL (`mysql://user:pass@host:3306/db`).
+4. Hapus folder `prisma/migrations` (jika baru mulai) atau siapkan strategi migrasi.
+5. Jalankan `npm run prisma:migrate`.
+
+### Q: Bagaimana cara membuat relasi antar tabel?
+**A:**
+Definisikan relasi di file `.prisma` masing-masing. Karena file akan digabung, Anda bisa mereferensikan model yang ada di file lain.
+**File `user.prisma`:**
+```prisma
+model User {
+  id    Int    @id
+  posts Post[] // Relasi ke Post
+}
+```
+**File `post.prisma`:**
+```prisma
+model Post {
+  id       Int  @id
+  authorId Int
+  author   User @relation(fields: [authorId], references: [id]) // Relasi ke User
+}
+```
+
+## Redis & Caching
+
+### Q: Saya tidak ingin pakai Redis di local, ribet installnya.
+**A:**
+Tenang, Lapeh otomatis mendeteksi jika Redis tidak berjalan dan akan menggunakan **In-Memory Mock** (simulasi Redis di RAM). Aplikasi tetap jalan normal tanpa error. Anda tidak perlu config apa-apa.
+
+### Q: Bagaimana cara clear cache Redis?
+**A:**
+Jika punya akses CLI Redis: `redis-cli FLUSHALL`.
+Atau via kode:
+```typescript
+import { redis } from "@/core/redis";
+await redis.flushall();
+```
+
+## Fitur & Kustomisasi
+
+### Q: Bagaimana cara handle File Upload?
+**A:**
+Gunakan `multer`. Framework sudah menyiapkannya di `src/routes/auth.ts` sebagai contoh (upload avatar).
+Anda bisa copy logic konfigurasi `multer` tersebut ke route lain.
+
+### Q: Bagaimana cara menambah middleware global baru?
+**A:**
+Buka `src/core/server.ts`. Di sana ada bagian `// Global Middlewares`. Tambahkan middleware Express Anda di situ:
+```typescript
+app.use(myCustomMiddleware);
+```
+
+### Q: Saya ingin mengubah port server.
+**A:**
+Cukup ubah variabel `PORT` di file `.env`. Defaultnya adalah `4000`.
+
+## Troubleshooting
+
+### Q: Error `EADDRINUSE: address already in use :::4000`
+**A:**
+Artinya port 4000 sedang dipakai program lain (atau instance Lapeh sebelumnya yang nyangkut).
+**Solusi:**
+1. Matikan terminal.
+2. Jalankan perintah kill (framework biasanya memberi saran commandnya saat error muncul).
+   - Windows: `taskkill /F /IM node.exe` (Hati-hati ini mematikan semua node process).
+   - Atau cari PID nya: `netstat -ano | findstr :4000`.
+
+### Q: Error `Unique constraint failed` saat seeding
+**A:**
+Data yang mau dimasukkan sudah ada (misal email `sa@sa.com`).
+Jalankan `npm run db:reset` untuk menghapus semua data dan mulai dari nol.

package/doc/id/PACKAGES.md

@@ -0,0 +1,66 @@
+# Referensi Package & Dependencies
+
+Dokumen ini menjelaskan fungsi dari setiap library (package) yang terinstall di Lapeh Framework, sehingga Anda mengerti kegunaan "alat-alat" yang ada di dalam kotak peralatan Anda.
+
+## Core Framework (Fondasi)
+
+Package-package ini adalah nyawa dari framework ini.
+
+| Package | Deskripsi | Kenapa Kita Pakai? |
+| :--- | :--- | :--- |
+| **`express`** | Web Framework untuk Node.js. | Standar industri, ringan, dan komunitasnya terbesar. |
+| **`dotenv`** | Memuat variabel dari file `.env`. | Agar konfigurasi rahasia (DB password, API Key) tidak di-hardcode. |
+| **`cors`** | Cross-Origin Resource Sharing. | Mengizinkan frontend (React/Vue) dari domain berbeda untuk mengakses API kita. |
+| **`helmet`** | Middleware keamanan HTTP headers. | Melindungi aplikasi dari serangan umum (XSS, Clickjacking) dengan mengatur header HTTP secara otomatis. |
+
+## Database & ORM
+
+| Package | Deskripsi | Kenapa Kita Pakai? |
+| :--- | :--- | :--- |
+| **`@prisma/client`** | Query builder & ORM. | Type-safe query database. Autocomplete-nya sangat membantu developer. |
+| **`pg`** | Driver PostgreSQL. | Driver native untuk koneksi ke database Postgres. |
+| **`@prisma/adapter-*`** | Adapter serverless. | (Opsional) Persiapan untuk deployment ke environment serverless (seperti Vercel/Neon). |
+
+## Authentication & Security
+
+| Package | Deskripsi | Kenapa Kita Pakai? |
+| :--- | :--- | :--- |
+| **`jsonwebtoken`** | Implementasi JWT. | Standar token untuk autentikasi stateless (API). |
+| **`bcryptjs`** | Hashing password. | Mengamankan password user di database (satu arah). |
+| **`express-rate-limit`** | Pembatas request. | Mencegah serangan DDoS ringan atau Brute Force login. |
+
+## Utilities & Helper
+
+| Package | Deskripsi | Kenapa Kita Pakai? |
+| :--- | :--- | :--- |
+| **`zod`** | Schema validation library. | Memvalidasi input user (req.body) dengan syntax yang kuat dan mudah dibaca. |
+| **`fast-json-stringify`** | Serializer JSON cepat. | Mengubah object ke JSON string 2x-3x lebih cepat dari `JSON.stringify` bawaan. |
+| **`uuid`** | Generator ID unik. | Membuat string acak unik (UUID v4). |
+| **`slugify`** | String formatter. | Mengubah "Judul Artikel Keren" menjadi `judul-artikel-keren` (URL friendly). |
+| **`multer`** | Middleware upload file. | Menangani `multipart/form-data` untuk upload gambar/dokumen. |
+| **`winston`** | Logger library. | Mencatat log aplikasi (error/info) ke file atau console dengan format rapi. |
+
+## Realtime & Caching
+
+| Package | Deskripsi | Kenapa Kita Pakai? |
+| :--- | :--- | :--- |
+| **`socket.io`** | Library WebSocket. | Fitur komunikasi real-time dua arah (chat, notifikasi live). |
+| **`ioredis`** | Client Redis yang robust. | Driver terbaik untuk Redis di Node.js. |
+| **`ioredis-mock`** | Simulasi Redis di memori. | Memungkinkan development tanpa perlu install Redis server asli (sangat berguna untuk pemula). |
+
+## Development Tools (DevDependencies)
+
+Package ini hanya dipakai saat koding, tidak ikut terinstall di server production.
+
+| Package | Deskripsi | Fungsi |
+| :--- | :--- | :--- |
+| **`typescript`** | Compiler TS. | Mengubah kode `.ts` menjadi `.js`. |
+| **`nodemon`** | Auto-restarter. | Restart server otomatis setiap kita save file. |
+| **`eslint`** | Linter (Polisi Kode). | Mencari potensi error dan variabel yang tidak terpakai. |
+| **`@types/*`** | Definisi Tipe. | Memberikan intellisense (saran kode) untuk library JavaScript biasa. |
+| **`prisma`** | Prisma CLI. | Alat untuk migrasi database (`prisma migrate`) dan generate client. |
+| **`tsc-alias`** | Path resolver. | Mengubah alias `@/core` menjadi path relatif `../core` saat build production. |
+
+---
+
+Dengan memahami daftar ini, Anda tahu persis apa yang terjadi di balik layar aplikasi Anda. Tidak ada "Bloatware", setiap package punya tujuan spesifik.

package/doc/id/PERFORMANCE.md

@@ -0,0 +1,91 @@
+# Panduan Performa & Skalabilitas Lapeh Framework
+
+Dokumen ini menjelaskan cara memaksimalkan performa aplikasi Lapeh Anda menggunakan fitur-fitur canggih seperti Fast-Serialization dan Clustering.
+
+## 1. High Performance Serialization (Fastify-Style)
+
+Express secara default menggunakan `JSON.stringify()` yang lambat karena harus memeriksa tipe data setiap field secara runtime. Lapeh mengadopsi teknik **Schema Based Serialization** (seperti Fastify) yang bisa meningkatkan throughput JSON hingga **2x-3x lipat**.
+
+### Cara Penggunaan
+
+Gunakan `sendFastSuccess` di controller Anda untuk endpoint yang membutuhkan performa tinggi (misalnya: list data yang besar).
+
+```typescript
+import { Request, Response } from "express";
+import { getSerializer, createResponseSchema } from "../core/serializer";
+import { sendFastSuccess } from "../utils/response";
+
+// 1. Definisikan Schema Output (JSON Schema Standard)
+const userSchema = {
+  type: "object",
+  properties: {
+    id: { type: "integer" },
+    name: { type: "string" },
+    email: { type: "string" },
+    // Password tidak dimasukkan, jadi otomatis tidak akan terkirim (aman!)
+  }
+};
+
+// 2. Compile Serializer (Otomatis dicache oleh framework)
+const userListSerializer = getSerializer("user-list", createResponseSchema({
+  type: "array",
+  items: userSchema
+}));
+
+export async function getUsers(req: Request, res: Response) {
+  const users = await prisma.users.findMany();
+
+  // 3. Kirim response super cepat
+  return sendFastSuccess(res, 200, userListSerializer, {
+    status: "success",
+    message: "Data fetched",
+    data: users
+  });
+}
+```
+
+---
+
+## 2. Horizontal Scaling (Load Balancer & Cluster)
+
+Lapeh dirancang untuk siap di-scale secara horizontal (menambah jumlah server, bukan memperbesar spesifikasi server).
+
+### Arsitektur Cluster
+- **Nginx**: Bertindak sebagai Load Balancer yang membagi trafik ke server-server aplikasi.
+- **Redis**: Menyimpan Session, Rate Limit, dan Cache agar bisa diakses oleh semua server (Shared State).
+- **App Instances**: Beberapa instance aplikasi Lapeh yang berjalan paralel.
+
+### Cara Menjalankan Cluster (Docker)
+
+Kami telah menyediakan konfigurasi siap pakai di `docker-compose.cluster.yml`.
+
+1. **Build & Run Cluster**:
+   ```bash
+   docker-compose -f docker-compose.cluster.yml up --build
+   ```
+
+2. **Akses Aplikasi**:
+   Buka `http://localhost:8080`.
+   Nginx akan otomatis membagi request Anda ke `app-1` atau `app-2`.
+
+3. **Cek Status**:
+   ```bash
+   docker-compose -f docker-compose.cluster.yml ps
+   ```
+
+### Konfigurasi Rate Limiter Terdistribusi
+Middleware `src/middleware/rateLimit.ts` telah diupdate untuk menggunakan Redis Store.
+Ini artinya jika User A terkena limit di Server 1, dia juga akan terblokir di Server 2.
+
+```typescript
+// src/middleware/rateLimit.ts
+store: redis ? new RedisStore({ sendCommand: ... }) : undefined
+```
+
+---
+
+## 3. Tips Optimasi Lainnya
+
+- **Gunakan `.lean()` / Select**: Saat query database, selalu pilih field yang dibutuhkan saja.
+- **Compression**: Aktifkan gzip/brotli di Nginx (sudah ada di config default Nginx umumnya).
+- **Keep-Alive**: Gunakan koneksi database yang persistent (sudah dihandle oleh Prisma).