lapeeh 1.0.0

package/readme.md

@@ -0,0 +1,357 @@
+# lapeeh Framework - Modern Node.js & TypeScript API Framework
+
+**lapeeh** adalah framework **Node.js** berbasis **Express** dan **TypeScript** yang dirancang untuk kecepatan dan skalabilitas. Menggabungkan fleksibilitas Express dengan struktur solid ala **Laravel** dan **NestJS**, lapeeh memberikan pengalaman development **REST API** yang cepat, terstandarisasi, dan siap produksi.
+
+Cocok untuk developer yang mencari **Express boilerplate** dengan fitur lengkap: Authentication, dan Zero-Config Redis.
+
+## 🚀 Fitur Utama
+
+- **Production Ready**: Struktur folder modular (MVC) yang mudah dikembangkan.
+- **TypeScript First**: Full type-safety untuk mengurangi runtime error.
+- **Database Agnostic**: Bebas pilih database dan ORM pilihan Anda.
+- **Standardized Structure**: Controller, Service, dan Route yang terpisah rapi.
+- **Auto CLI Generator**: Buat modul dan controller dengan satu perintah.
+- **Smart Caching**: Otomatis menggunakan Redis jika tersedia, fallback ke in-memory jika tidak.
+- **Secure by Default**: Dilengkapi Helmet, Rate Limiting, CORS, dan JWT Auth.
+- **Robust Validation**: Validasi request otomatis menggunakan Zod.
+- **High Performance**: Mendukung Fast-Serialization (Fastify-style) untuk response JSON super cepat.
+- **Scalable**: Siap untuk deployment Cluster/Load Balancer dengan Redis Store.
+
+## 🔮 Roadmap (Rencana Masa Depan)
+
+lapeeh Framework akan terus berkembang menjadi solusi Enterprise yang lengkap. Kami memiliki rencana besar untuk fitur-fitur seperti **Job Queues**, **Storage Abstraction (S3)**, **Mailer**, dan **OpenAPI Generator**.
+
+Lihat detail rencana pengembangan di **[ROADMAP.md](doc/ROADMAP.md)**.
+
+## 🤝 Berkontribusi (Open Source)
+
+lapeeh adalah proyek Open Source dan kami sangat terbuka untuk kontribusi dari komunitas! Baik itu perbaikan bug, penambahan fitur, atau perbaikan dokumentasi.
+
+Ingin ikut berkontribusi? Silakan baca **[Panduan Kontribusi (CONTRIBUTING.md)](doc/CONTRIBUTING.md)** untuk memulai.
+
+## 📚 Dokumentasi Lengkap
+
+Kami menyusun "Learning Path" agar Anda bisa memahami framework ini dari nol hingga mahir.
+
+### 🐣 Level 1: Pemula (Wajib Baca)
+
+- **[Pengenalan Framework](doc/INTRODUCTION.md)**: Mengapa framework ini ada? Apa bedanya dengan yang lain?
+- **[Getting Started](doc/GETTING_STARTED.md)**: Instalasi dan setup awal.
+- **[Bedah Struktur Folder](doc/STRUCTURE.md)**: Pahami fungsi setiap file dan direktori.
+- **[Referensi Package](doc/PACKAGES.md)**: Penjelasan kegunaan setiap library yang terinstall.
+- **[Cheatsheet (Contekan)](doc/CHEATSHEET.md)**: Daftar perintah & kode cepat.
+
+### 🔨 Level 2: Membangun Aplikasi
+
+- **[CLI Tools](doc/CLI.md)**: Percepat kerja dengan generator kode (`make:module`, dll).
+- **[Tutorial Studi Kasus](doc/TUTORIAL.md)**: Bikin API "Perpustakaan" dari nol sampai jadi.
+- **[Fitur & Konsep Inti](doc/FEATURES.md)**: Validasi, Auth, RBAC, dan Serializer.
+
+### 🚀 Level 3: Mahir & Production
+
+- **[Performance Guide](doc/PERFORMANCE.md)**: Tips optimasi high-scale app.
+- **[Security Best Practices](doc/SECURITY.md)**: Panduan mengamankan aplikasi.
+- **[Deployment Guide](doc/DEPLOYMENT.md)**: Cara deploy ke VPS, Docker, atau Cloud.
+- **[FAQ & Troubleshooting](doc/FAQ.md)**: Solusi masalah umum.
+- **[Changelog](doc/CHANGELOG.md)**: Riwayat versi.
+
+## 📦 Instalasi & Penggunaan
+
+Anda dapat menginstall framework ini menggunakan versi terbaru:
+
+```bash
+npx lapeeh@latest nama-project-anda
+```
+
+Perintah di atas akan membuat proyek **bersih** (clean slate):
+
+- Struktur folder dibuat.
+- Dependensi diinstall.
+- Folder `bin` dan `lib` framework tersembunyi di `node_modules` agar root proyek Anda tetap rapi.
+
+### Apa yang terjadi otomatis?
+
+1. Struktur project dibuat (Core framework tersembunyi sebagai dependency).
+2. Dependencies diinstall.
+3. **JWT Secret** di-generate otomatis.
+
+Masuk ke folder project dan jalankan:
+
+```bash
+cd nama-project-anda
+npm run dev
+```
+
+> **Catatan**: Perintah `npm run dev` sekarang menggunakan CLI internal framework (`lapeeh dev`), memberikan pengalaman development yang lebih stabil dan terstandarisasi. Core framework (`bin` dan `lib`) tidak lagi memenuhi root folder Anda, tetapi tersimpan aman sebagai dependency.
+
+Server akan berjalan di `http://localhost:8000`.
+
+### 🛡️ Keamanan & Pembaruan
+
+Framework ini didesain dengan memprioritaskan keamanan:
+
+- **Zero-Vulnerability Policy**: Kami secara rutin melakukan audit dependensi (`npm audit`) untuk memastikan tidak ada celah keamanan.
+- **Framework-as-Dependency**: Dengan menyembunyikan core logic di `node_modules`, pembaruan framework menjadi lebih mudah (cukup update versi `@lapeeh/lapeeh` di `package.json`) tanpa merusak kode aplikasi Anda.
+
+---
+
+## 🔄 Upgrade Project
+
+Jika Anda memiliki project lama yang dibuat dengan versi lapeeh sebelumnya dan ingin memperbarui struktur, scripts, dan konfigurasi ke standar terbaru (termasuk keamanan Redis baru), Anda tidak perlu membuat project ulang.
+
+Cukup jalankan perintah ini di dalam folder project Anda:
+
+```bash
+npx lapeeh@latest upgrade
+```
+
+Perintah ini akan secara otomatis:
+
+1.  Mengupdate `scripts/` (termasuk generator controller baru).
+2.  Mengupdate `docker-compose.yml` (keamanan Redis).
+3.  Mengupdate dependencies di `package.json`.
+4.  Menambahkan konfigurasi `.vscode` dan `tsconfig` terbaru.
+
+> **Catatan:** File `.env` Anda **tidak akan ditimpa**, namun kami akan mengupdate `.env.example` sebagai referensi konfigurasi terbaru.
+
+## 🧠 Zero-Config Redis
+
+lapeeh otomatis mendeteksi ketersediaan Redis.
+
+1.  **Auto-Discovery**: Mencoba terhubung ke Redis URL di `.env` (`REDIS_URL`).
+2.  **Smart Fallback**: Jika Redis tidak tersedia atau koneksi gagal, otomatis beralih ke **In-Memory Mock**.
+    - Tidak perlu install Redis di local development.
+    - Fitur rate-limiting dan caching tetap berjalan (namun data hilang saat restart).
+3.  **Production Safety**: Memberikan peringatan log jika berjalan di Production menggunakan Mock.
+
+**Force Mock Mode:**
+Anda bisa memaksa menggunakan mock (misal untuk testing) dengan menambahkan env variable:
+
+```env
+NO_REDIS=true
+```
+
+### Optional: Menggunakan Real Redis dengan Docker
+
+Jika Anda ingin menggunakan Redis yang sebenarnya di local environment, kami telah menyertakan konfigurasi `docker-compose.yml` yang aman (menggunakan ACL).
+
+1.  Jalankan Redis container:
+
+    ```bash
+    docker-compose up -d
+    ```
+
+2.  Uncomment konfigurasi Redis di file `.env` Anda:
+
+    ```env
+    REDIS_URL="redis://lapeeh:12341234@localhost:6379"
+    ```
+
+    > **Credential Default:**
+    >
+    > - User: `lapeeh`
+    > - Password: `12341234`
+
+## 🛠 Development Tools
+
+API lapeeh menyediakan tools untuk mempercepat development, mirip dengan `artisan` di Laravel.
+
+### 1. Membuat Module (Resource)
+
+Membuat Controller, Service, dan Route sekaligus.
+
+```bash
+npm run make:module NamaResource
+# Contoh: npm run make:module Product
+```
+
+Command ini akan membuat:
+
+- `src/controllers/product.controller.ts`
+- `src/services/product.service.ts`
+- `src/routes/product.route.ts` (dan otomatis didaftarkan di `src/routes/index.ts` jika memungkinkan)
+
+### 2. Membuat Controller
+
+Membuat file Controller baru. Gunakan flag `-r` untuk membuat controller lengkap dengan method CRUD (index, show, store, update, destroy).
+
+```bash
+npm run make:controller NamaController
+# Contoh Basic: npm run make:controller PaymentController
+
+# Contoh Resource (CRUD Lengkap):
+npm run make:controller PaymentController -r
+```
+
+### 3. Database (No-ORM)
+
+Since v3.0.0, lapeeh Framework **does not include a default ORM** (like Prisma). We believe in giving you full control over your database stack.
+
+You can freely choose to use:
+
+- **Prisma** (Manual installation)
+- **TypeORM**
+- **Drizzle ORM**
+- **Mongoose**
+- **Raw SQL** (pg, mysql2)
+
+The framework provides a `Validator` class for request validation and a `Serializer` for response formatting, but data persistence is up to you.
+
+### 4. Generate JWT Secret
+
+Jika Anda perlu me-refresh secret key JWT:
+
+```bash
+npm run generate:jwt
+```
+
+### 5. Maintenance (Clear Config)
+
+Membersihkan cache framework, NPM, build artifacts, dan temporary files (sangat berguna jika mengalami isu cache aneh atau ingin reset environment development).
+
+```bash
+npm run config:clear
+```
+
+- Menghapus `node_modules/.cache`
+- Menghapus `dist/`
+- Menghapus `dump.rdb` (Redis Persistence)
+- Membersihkan `npm cache`
+
+---
+
+## 📂 Struktur Folder
+
+```text
+src/
+├── controllers/     # Logika Request & Response
+├── services/        # Business Logic
+├── routes/          # Definisi Route API
+├── middleware/      # Auth, Validation, Error Handling
+├── schema/          # Zod Validation Schemas
+├── utils/           # Helper Functions
+└── index.ts         # App Entry Point
+```
+
+## 📝 Lisensi
+
+MIT
+
+---
+
+## 🚀 Deployment Guide
+
+### 1) Build
+
+- Build: `npm run build`
+- Start (dev): `npm run start`
+- Start (prod): `npm run start:prod`
+
+### 2) Production Environment
+
+- Pastikan `.env` berisi kredensial production:
+  - `JWT_SECRET` (gunakan `npm run generate:jwt` untuk mengganti)
+  - Database credentials (sesuai pilihan ORM/DB Anda)
+
+### 3) Menjalankan dengan PM2
+
+- Install PM2:
+
+```bash
+npm i -g pm2
+```
+
+- Jalankan aplikasi:
+
+```bash
+pm2 start dist/src/index.js --name lapeeh-api --time
+```
+
+- Simpan proses agar auto-start saat reboot:
+
+```bash
+pm2 save
+pm2 startup
+```
+
+- Monitoring:
+
+```bash
+pm2 status
+pm2 logs lapeeh-api
+pm2 restart lapeeh-api
+```
+
+### 4) Nginx Reverse Proxy (Recommended)
+
+- Buat server block `/etc/nginx/sites-available/lapeeh`:
+
+```nginx
+server {
+  listen 80;
+  server_name example.com;
+
+  location / {
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_pass http://127.0.0.1:8000;
+  }
+}
+```
+
+- Aktifkan:
+
+```bash
+sudo ln -s /etc/nginx/sites-available/lapeeh /etc/nginx/sites-enabled/lapeeh
+sudo nginx -t
+sudo systemctl reload nginx
+```
+
+- SSL (opsional, Certbot):
+
+```bash
+sudo apt install certbot python3-certbot-nginx -y
+sudo certbot --nginx -d example.com
+```
+
+### 5) Apache 2 Reverse Proxy (Alternatif)
+
+- Enable modul proxy:
+
+```bash
+sudo a2enmod proxy proxy_http headers
+sudo systemctl reload apache2
+```
+
+- Buat vhost `/etc/apache2/sites-available/lapeeh.conf`:
+
+```apache
+<VirtualHost *:80>
+  ServerName example.com
+  ProxyPreserveHost On
+  ProxyRequests Off
+  <Proxy *>
+    Require all granted
+  </Proxy>
+  ProxyPass / http://127.0.0.1:8000/
+  ProxyPassReverse / http://127.0.0.1:8000/
+  ErrorLog ${APACHE_LOG_DIR}/lapeeh-error.log
+  CustomLog ${APACHE_LOG_DIR}/lapeeh-access.log combined
+</VirtualHost>
+```
+
+- Aktifkan:
+
+```bash
+sudo a2ensite lapeeh.conf
+sudo apachectl configtest
+sudo systemctl reload apache2
+```
+
+### 6) Checklist Produksi
+
+- `pm2 status` menunjukkan proses hidup
+- Proxy (Nginx/Apache) menuju port aplikasi (default 8000)
+- `.env` aman dan tidak di-commit ke repository

package/scripts/check-update.js

@@ -0,0 +1,92 @@
+const https = require('https');
+const fs = require('fs');
+const path = require('path');
+
+// --- KONFIGURASI ---
+// Ganti URL ini dengan URL raw package.json dari repository GitHub/GitLab Anda
+// Contoh: 'https://raw.githubusercontent.com/username/project-name/main/package.json'
+// Jika package dipublish ke NPM, Anda bisa menggunakan registry NPM.
+const REPO_VERSION_URL = 'https://registry.npmjs.org/lapeeh/latest'; 
+const TIMEOUT = 2000; // Timeout 2 detik agar tidak terlalu lama menunggu
+
+const packageJson = require('../package.json');
+// Cek apakah ada key "lapeeh" di dependencies (project user)
+// Jika tidak ada, fallback ke version package.json (mungkin ini repo framework itu sendiri)
+const currentVersion = packageJson.dependencies?.['lapeeh'] || packageJson.version;
+
+function checkForUpdates() {
+  if (!REPO_VERSION_URL) return;
+
+  const req = https.get(REPO_VERSION_URL, { 
+    headers: { 'User-Agent': 'NodeJS Update Checker' },
+    timeout: TIMEOUT 
+  }, (res) => {
+    let data = '';
+
+    if (res.statusCode !== 200) {
+      // Silent fail jika URL tidak bisa diakses
+      return;
+    }
+
+    res.on('data', (chunk) => {
+      data += chunk;
+    });
+
+    res.on('end', () => {
+      try {
+        const remoteJson = JSON.parse(data);
+        // Jika cek ke NPM, version ada di root object atau 'version'
+        // Jika cek ke raw github, structure sama dengan package.json
+        const latestVersion = remoteJson.version || remoteJson['dist-tags']?.latest;
+
+        if (latestVersion && isNewer(latestVersion, currentVersion)) {
+          showUpdateMessage(latestVersion, currentVersion);
+        }
+      } catch (e) {
+        // Ignore parsing errors
+      }
+    });
+  });
+
+  req.on('error', (e) => {
+    // Ignore network errors
+  });
+
+  req.end();
+}
+
+function isNewer(latest, current) {
+  const lParts = latest.split('.').map(Number);
+  const cParts = current.split('.').map(Number);
+  
+  for (let i = 0; i < 3; i++) {
+    if (lParts[i] > cParts[i]) return true;
+    if (lParts[i] < cParts[i]) return false;
+  }
+  return false;
+}
+
+function showUpdateMessage(latest, current) {
+    const reset = "\x1b[0m";
+    const bright = "\x1b[1m";
+    const fgYellow = "\x1b[33m";
+    const fgCyan = "\x1b[36m";
+    
+    console.log('\n');
+    console.log(`${fgYellow}┌─────────────────────────────────────────────────────────────┐${reset}`);
+    console.log(`${fgYellow}│                                                             │${reset}`);
+    console.log(`${fgYellow}│   ${bright}UPDATE FRAMEWORK TERSEDIA!${reset}${fgYellow}                                │${reset}`);
+    console.log(`${fgYellow}│                                                             │${reset}`);
+    console.log(`${fgYellow}│   Versi Lokal   : ${fgCyan}${current}${reset}${fgYellow}                                      │${reset}`);
+    console.log(`${fgYellow}│   Versi Terbaru : ${fgCyan}${latest}${reset}${fgYellow}                                      │${reset}`);
+    console.log(`${fgYellow}│                                                             │${reset}`);
+    console.log(`${fgYellow}│   Silakan cek repository untuk melihat perubahan terbaru.   │${reset}`);
+    console.log(`${fgYellow}│                                                             │${reset}`);
+    console.log(`${fgYellow}│   Untuk upgrade jalankan:                                   │${reset}`);
+    console.log(`${fgYellow}│   ${fgCyan}npm install lapeeh@latest${reset}${fgYellow}                                    │${reset}`);
+    console.log(`${fgYellow}│                                                             │${reset}`);
+    console.log(`${fgYellow}└─────────────────────────────────────────────────────────────┘${reset}`);
+    console.log('\n');
+}
+
+checkForUpdates();

package/scripts/config-clear.js

@@ -0,0 +1,45 @@
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const rootDir = path.join(__dirname, '..');
+
+console.log('🧹 Starting cleanup process...');
+
+// 1. Remove dist folder (Build artifacts)
+const distDir = path.join(rootDir, 'dist');
+if (fs.existsSync(distDir)) {
+  console.log('🗑️  Removing dist/ folder...');
+  fs.rmSync(distDir, { recursive: true, force: true });
+}
+
+// 2. Remove node_modules/.cache (Framework caches: ts-node, eslint, etc)
+const nmCacheDir = path.join(rootDir, 'node_modules', '.cache');
+if (fs.existsSync(nmCacheDir)) {
+  console.log('🗑️  Removing node_modules/.cache...');
+  fs.rmSync(nmCacheDir, { recursive: true, force: true });
+}
+
+// 3. Remove Redis local persistence file (dump.rdb)
+const dumpRdb = path.join(rootDir, 'dump.rdb');
+if (fs.existsSync(dumpRdb)) {
+  console.log('🗑️  Removing dump.rdb (Redis persistence)...');
+  fs.unlinkSync(dumpRdb);
+}
+
+// 4. Remove Coverage folder (if exists)
+const coverageDir = path.join(rootDir, 'coverage');
+if (fs.existsSync(coverageDir)) {
+  console.log('🗑️  Removing coverage/ folder...');
+  fs.rmSync(coverageDir, { recursive: true, force: true });
+}
+
+// 5. Clear NPM Cache
+try {
+  console.log('📦 Clearing NPM cache...');
+  execSync('npm cache clean --force', { stdio: 'inherit' });
+} catch (error) {
+  console.warn('⚠️  Warning: Could not clear NPM cache. You might need admin privileges.');
+}
+
+console.log('✨ Cleanup complete! Project is fresh.');

package/scripts/generate-jwt-secret.js

@@ -0,0 +1,38 @@
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const envPath = path.join(__dirname, '..', '.env');
+
+function generateSecret() {
+  return crypto.randomBytes(64).toString('hex');
+}
+
+try {
+  const secret = generateSecret();
+  let envContent = '';
+
+  if (fs.existsSync(envPath)) {
+    envContent = fs.readFileSync(envPath, 'utf8');
+  } else {
+    console.log('.env file not found, creating one...');
+  }
+
+  // Check if JWT_SECRET exists
+  if (envContent.match(/^JWT_SECRET=/m)) {
+    envContent = envContent.replace(/^JWT_SECRET=.*/m, `JWT_SECRET="${secret}"`);
+  } else {
+    // Ensure there is a newline before appending if the file is not empty
+    if (envContent && !envContent.endsWith('\n')) {
+      envContent += '\n';
+    }
+    envContent += `JWT_SECRET="${secret}"\n`;
+  }
+
+  fs.writeFileSync(envPath, envContent);
+  console.log('✅ JWT Secret generated and updated in .env file.');
+  console.log('🔑 New Secret has been set.');
+} catch (error) {
+  console.error('❌ Error updating .env file:', error);
+  process.exit(1);
+}

package/scripts/init-project.js

@@ -0,0 +1,84 @@
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+const readline = require("readline");
+
+const rootDir = path.join(__dirname, "..");
+const envExample = path.join(rootDir, ".env.example");
+const envFile = path.join(rootDir, ".env");
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+const ask = (query, defaultVal) => {
+  return new Promise((resolve) => {
+    rl.question(`${query} ${defaultVal ? `[${defaultVal}]` : ""}: `, (answer) => {
+      resolve(answer.trim() || defaultVal);
+    });
+  });
+};
+
+const selectOption = async (query, options) => {
+  console.log(query);
+  options.forEach((opt, idx) => {
+    console.log(`   [${opt.key}] ${opt.label}`);
+  });
+  
+  while (true) {
+    const answer = await ask(">", options[0].key); // Default to first option
+    const selected = options.find(o => o.key.toLowerCase() === answer.toLowerCase());
+    if (selected) return selected;
+    
+    // Check if user entered the full name or label
+    const byLabel = options.find(o => o.label.toLowerCase().includes(answer.toLowerCase()));
+    if (byLabel) return byLabel;
+
+    console.log("Pilihan tidak valid. Silakan coba lagi.");
+  }
+};
+
+(async () => {
+  console.log("🚀 Starting project initialization...");
+
+  try {
+    // Close readline as we are done with input
+    rl.close();
+
+    // 1. Setup .env
+    console.log("\n📄 Setting up .env...");
+    let envContent = "";
+    if (fs.existsSync(envExample)) {
+      envContent = fs.readFileSync(envExample, "utf8");
+    } else {
+      // Fallback minimal env if example missing
+      envContent = `PORT=8000\nJWT_SECRET="replace_this"\n`;
+    }
+
+    fs.writeFileSync(envFile, envContent);
+    console.log("✅ .env created.");
+
+    // 3. Install dependencies
+    console.log("\n📦 Installing dependencies...");
+    execSync("npm install", { stdio: "inherit", cwd: rootDir });
+
+    // 5. Generate JWT Secret
+    console.log("\n🔑 Generating JWT Secret...");
+    try {
+        execSync("node scripts/generate-jwt-secret.js", {
+            stdio: "inherit",
+            cwd: rootDir,
+        });
+    } catch (e) {
+        console.warn("⚠️ Failed to generate JWT secret automatically.");
+    }
+
+    console.log("\n✅ Setup complete! You can now run:");
+    console.log("   npm run dev");
+
+  } catch (error) {
+    console.error("\n❌ Setup failed:", error.message);
+    process.exit(1);
+  }
+})();