lapeh 2.4.5 → 2.4.7

package/doc/en/CLI.md

@@ -0,0 +1,101 @@
+# CLI Tools & Scripts
+
+Lapeh Framework comes with various CLI scripts to speed up the development process, ranging from code generation to database management.
+
+All commands are executed using `npm run <command>`.
+
+> **Info:** Behind the scenes, these `npm run` scripts call the internal framework CLI (`lapeh`). You can also run these commands directly using `npx lapeh <command>`.
+
+## Core Commands
+
+Main commands to run the application:
+
+### 1. Development Server (`dev`)
+Runs the server in development mode with hot-reload feature.
+
+```bash
+npm run dev
+# or
+npx lapeh dev
+```
+
+### 2. Production Server (`start`)
+Runs the server in production mode (ensure it has been built).
+
+```bash
+npm run start
+# or
+npx lapeh start
+```
+
+### 3. Build Project (`build`)
+Compiles TypeScript code to JavaScript in the `dist` folder.
+
+```bash
+npm run build
+# or
+npx lapeh build
+```
+
+## Code Generators
+
+Use these commands to create boilerplate files automatically.
+
+### 1. Create Complete Module (`make:module`)
+Creates Controller, Route, and Model (Schema) at once.
+
+```bash
+npm run make:module <module-name>
+```
+**Example:** `npm run make:module Product`
+
+Output:
+- `src/controllers/productController.ts`
+- `src/routes/product.ts`
+- `src/models/product.prisma`
+
+### 2. Create Controller (`make:controller`)
+Only creates a controller file with basic CRUD methods.
+
+```bash
+npm run make:controller <controller-name>
+```
+**Example:** `npm run make:controller Order` (Will create `src/controllers/orderController.ts`)
+
+### 3. Create Database Model (`make:model`)
+Only creates a new Prisma schema file.
+
+```bash
+npm run make:model <model-name>
+```
+**Example:** `npm run make:model Transaction` (Will create `src/models/transaction.prisma`)
+
+## Database Management (Prisma)
+
+This framework uses a **Multi-File Schema** system. You don't edit `schema.prisma` directly, but instead edit small files in `src/models/*.prisma`.
+
+### 1. Database Migration (`prisma:migrate`)
+Run this every time you change a model definition in `src/models/*.prisma`.
+
+```bash
+npm run prisma:migrate
+```
+This command will:
+1. Merge all `.prisma` files in `src/models/` into one `prisma/schema.prisma`.
+2. Create SQL migration files.
+3. Apply changes to the local database.
+4. Regenerate Prisma Client (Type Definitions).
+
+### 2. Deploy to Production (`prisma:deploy`)
+Use in production server. Only applies existing migrations without resetting data.
+
+```bash
+npm run prisma:deploy
+```
+
+### 3. Database Studio (`db:studio`)
+Opens a GUI in the browser to view and edit database data.
+
+```bash
+npm run db:studio
+```

package/doc/{DEPLOYMENT.md → en/DEPLOYMENT.md}

@@ -49,21 +49,25 @@ npm run prisma:deploy
 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
@@ -75,7 +79,104 @@ Lapeh kini menyertakan konfigurasi otomatis PM2 (`ecosystem.config.js`).
     pm2 startup
     ```
 
-### 6. Reverse Proxy (Nginx)
+### ❓ 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:

package/doc/en/FEATURES.md

@@ -0,0 +1,99 @@
+# Features & Core Concepts
+
+This document explains the key features of Lapeh Framework and how to use them in depth.
+
+## 1. Data Validation (Laravel-Style)
+
+The framework provides a `Validator` utility inspired by Laravel, using `zod` behind the scenes but with an API that is more string-based and readable.
+
+**Location:** `@lapeh/utils/validator`
+
+### Basic Usage
+
+```typescript
+import { Validator } from "@lapeh/utils/validator";
+
+export async function createProduct(req: Request, res: Response) {
+  const validator = await Validator.make(req.body, {
+    name: "required|string|min:3",
+    price: "required|number|min:1000",
+    email: "required|email|unique:user,email", // Check unique in user table email column
+    category_id: "required|exists:category,id", // Check exists in category table id column
+    photo: "required|image|max:2048", // Validate file upload (Max 2MB)
+  });
+
+  if (validator.fails()) {
+    return sendError(res, 400, "Validation failed", validator.errors());
+  }
+
+  const data = validator.validated();
+  // Continue saving process...
+}
+```
+
+### Available Rules
+
+- `required`: Must be filled.
+- `string`, `number`, `boolean`: Data type.
+- `email`: Valid email format.
+- `min:X`, `max:X`: String length or number value.
+- `unique:table,column`: Ensure value does not exist in database (Async).
+- `exists:table,column`: Ensure value exists in database (Async).
+- `image`: File must be an image (jpg, png, webp, etc).
+- `mimes:types`: File must be a specific type (e.g., `mimes:pdf,docx`).
+
+## 2. High Performance Response (Fastify-Style)
+
+For endpoints requiring high performance (e.g., large data lists), use schema-based serialization. This is much faster than standard Express `res.json`.
+
+**Location:** `@/utils/response`, `@/core/serializer`
+
+### Implementation Steps
+
+1. **Define Output Schema**
+   Match with the fields you want to show to the user.
+
+   ```typescript
+   const productSchema = {
+     type: "object",
+     properties: {
+       id: { type: "string" }, // BigInt automatically becomes string
+       name: { type: "string" },
+       price: { type: "number" },
+     },
+   };
+   ```
+
+2. **Create Serializer (Cached)**
+   Store outside the handler function so it compiles only once.
+
+   ```typescript
+   import { getSerializer, createResponseSchema } from "@/core/serializer";
+
+   const productSerializer = getSerializer(
+     "product-single",
+     createResponseSchema(productSchema)
+   );
+   ```
+
+3. **Send Response**
+
+   ```typescript
+   import { sendFastSuccess } from "@lapeh/utils/response";
+
+   // Inside controller
+   sendFastSuccess(res, 200, productSerializer, {
+     status: "success",
+     message: "Data retrieved",
+     data: productData,
+   });
+   ```
+
+## 3. Authentication & Authorization (RBAC)
+
+The authentication system uses JWT (JSON Web Token) and supports Role-Based Access Control.
+
+### Auth Middleware
+
+- `requireAuth`: Ensures user is logged in (sends header `Authorization: Bearer <token>`).
+- `requireAdmin`: Ensures user is logged in AND has role `admin` or `super_admin`.

package/doc/en/GETTING_STARTED.md

@@ -0,0 +1,101 @@
+# Getting Started with Lapeh Framework
+
+Welcome to the official documentation for **Lapeh Framework**. This guide will help you get started with installation, configuration, and understanding the basic project structure.
+
+## System Requirements
+
+Before you begin, ensure your system meets the following requirements:
+
+- **Node.js**: Version 18.x or newer.
+- **Database**: PostgreSQL (Recommended) or MySQL/MariaDB.
+- **Package Manager**: NPM (bundled with Node.js).
+
+## Installation
+
+The easiest way to start is by using the `npx` CLI generator.
+
+### 1. Create a New Project
+
+Run the following command in your terminal:
+
+```bash
+npx lapeh@latest your-project-name
+```
+
+Or for a full setup (with dummy user & role data):
+
+```bash
+npx lapeh@latest your-project-name --full
+```
+
+### 2. Initial Setup
+
+Once the project is created, navigate into the project directory and run the setup wizard:
+
+```bash
+cd your-project-name
+npm run first
+```
+
+This script will automatically perform the following:
+
+1.  Copy `.env.example` to `.env`.
+2.  Install all dependencies (`npm install`).
+3.  Generate a secure **JWT Secret**.
+4.  Run database migrations (create tables).
+5.  Run the seeder (populate initial data).
+
+### 3. Run Development Server
+
+```bash
+npm run dev
+```
+
+The server will run at `http://localhost:4000` (or the port specified in `.env`).
+
+## Directory Structure
+
+Here is the standard folder structure of Lapeh Framework:
+
+```
+my-app/
+├── bin/                  # CLI scripts for npx
+├── doc/                  # Project documentation
+├── prisma/               # Database Configuration & Schema
+│   ├── migrations/       # Database migration history files
+│   ├── base.prisma.template # Database configuration template
+│   ├── schema.prisma     # Combined schema file (Auto-generated)
+│   └── seed.ts           # Script for populating initial data
+├── scripts/              # Utility scripts (Generator, Compiler)
+├── src/                  # Main application source code
+│   ├── controllers/      # Business logic (Request handlers)
+│   ├── core/             # Core configuration (DB, Redis, Server)
+│   ├── middleware/       # Express Middleware (Auth, RateLimit)
+│   ├── models/           # Prisma Schema definitions per feature
+│   ├── routes/           # API routing definitions
+│   ├── utils/            # Helper functions (Response, Validator)
+│   └── index.ts          # Application entry point
+├── .env                  # Environment variables (Secrets)
+├── package.json          # NPM Dependencies & Scripts
+└── tsconfig.json         # TypeScript Configuration
+```
+
+## Environment Configuration (.env)
+
+The `.env` file stores important configurations. Here are the key variables:
+
+```ini
+# Server
+PORT=4000
+NODE_ENV=development
+
+# Database (Change according to your credentials)
+DATABASE_URL="postgresql://user:password@localhost:5432/mydb?schema=public"
+
+# Security
+JWT_SECRET="super-long-and-random-secret"
+ACCESS_TOKEN_EXPIRES_IN=3600 # 1 hour
+
+# Redis (Optional - automatically mocked if absent)
+REDIS_URL="redis://localhost:6379"
+```

package/doc/en/INTRODUCTION.md

@@ -0,0 +1,60 @@
+# Introduction to Lapeh Framework
+
+## What is Lapeh?
+
+**Lapeh** is a Backend Framework for Node.js built on top of **Express** and **TypeScript**.
+
+If you have ever used **Laravel** (PHP) or **NestJS** (Node.js), you will feel very familiar. Lapeh adopts the philosophy of ease-of-use & clean structure from Laravel, while maintaining the flexibility and speed of Express.
+
+The name "Lapeh" comes from the Minang language which means "Loose" or "Free", symbolizing the freedom for developers to build applications quickly without being burdened by complicated configurations.
+
+## Why was Lapeh Created?
+
+In the Node.js ecosystem, developers often experience "Decision Fatigue":
+- "Which ORM to use? Prisma, TypeORM, or Drizzle?"
+- "Validation using Joi, Zod, or express-validator?"
+- "How about the folder structure? MVC? Clean Architecture?"
+- "How to handle Auth?"
+
+Lapeh answers all of that with **Opinionated Defaults**:
+1.  **ORM**: Prisma (Current industry standard).
+2.  **Validation**: Zod (with Laravel-style wrapper syntax).
+3.  **Structure**: Modular MVC (Controller, Model, Route separated but cohesive).
+4.  **Auth**: Ready-to-use JWT + RBAC (Role Based Access Control).
+
+## Comparison with Other Frameworks
+
+| Feature | Express (Raw) | NestJS | Lapeh Framework |
+| :--- | :--- | :--- | :--- |
+| **Learning Curve** | Low (but confusing structure) | High (Angular-style, Decorators) | **Medium** (Express + Clear Structure) |
+| **Boilerplate** | Empty | Very Heavy | **Just Right (Ready to use)** |
+| **Type Safety** | Manual | Strict | **Strict (Native TypeScript)** |
+| **Dev Speed** | Slow (manual setup) | Medium | **Fast (CLI Generator)** |
+| **Flexibility** | Very High | Rigid | **High** |
+
+## "The Lapeh Way" Philosophy
+
+1.  **Developer Experience (DX) First**: CLI tools, clear error messages, and hot-reload are priorities.
+2.  **Performance by Default**: Fast JSON serialization (Fastify-style) and integrated Redis caching.
+3.  **Explicit is Better than Implicit**: No "magic" that is too dark. Your controller code is standard Express code that you understand.
+4.  **Production Ready**: Security (Helmet, Rate Limit) and Scalability (Docker, Cluster) are not afterthoughts, but built-in.
+
+## Request Lifecycle
+
+How does Lapeh handle a single request from a user?
+
+1.  **Incoming Request** (`GET /api/users`)
+2.  **Security Middleware**: Helmet (Headers), CORS, Rate Limiter.
+3.  **Global Middleware**: Request Logger, Body Parser (JSON).
+4.  **Routing**: Matching URL in `src/routes/`.
+5.  **Auth Middleware** (Optional): Check JWT token & Role.
+6.  **Validator** (Optional): Validate body/query input.
+7.  **Controller**: Main business logic executed.
+    - Call Database (Prisma).
+    - Call Cache (Redis).
+8.  **Serializer**: Data formatted & sanitized (e.g., hide password).
+9.  **Response**: JSON sent back to user.
+
+---
+
+**Next:** Learn about the folder structure in [Project Structure](structure.md).

package/doc/en/STRUCTURE.md

@@ -0,0 +1,90 @@
+# Project Structure Breakdown
+
+To fully understand Lapeh Framework, you need to know what each file and folder does. Here is a complete "Tour" of the project directory.
+
+## Root Directory
+
+| File/Folder          | Description                                                                    |
+| :------------------- | :----------------------------------------------------------------------------- |
+| `bin/`               | Contains execution scripts for CLI (`npx lapeh`). You rarely touch this.       |
+| `doc/`               | Project documentation resides here.                                            |
+| `lib/`               | **Framework Core**. Internal parts of the framework you rarely touch.          |
+| `prisma/`            | The heart of Database configuration.                                           |
+| `scripts/`           | Collection of Node.js utility scripts (generators, schema compilers, etc).     |
+| `src/`               | **Main Source Code**. 99% of your coding happens here.                         |
+| `.env`               | Secret variables (Database URL, API Keys). **Do not commit this file to Git!** |
+| `docker-compose.yml` | Docker configuration for running local Database & Redis.                       |
+| `nodemon.json`       | Auto-restart configuration during development.                                 |
+| `package.json`       | List of libraries (dependencies) and commands (`npm run ...`).                 |
+| `tsconfig.json`      | TypeScript configuration.                                                      |
+
+## `src/` Folder (Source Code - User Space)
+
+This is where you work every day.
+
+### `src/controllers/`
+
+Contains application logic. Controllers receive Requests, process them, and return Responses.
+
+- **Example**: `authController.ts` handles login/register.
+- **Tip**: Do not put overly complex _business logic_ here. Use Services (optional) if the controller gets too fat.
+
+### `src/models/`
+
+Contains database table definitions (Prisma Schema).
+
+- **Unique in Lapeh**: We break down the large `schema.prisma` into small files per feature (e.g., `user.prisma`, `product.prisma`) for easier management. The `prisma:migrate` script will merge them later.
+
+### `src/routes/`
+
+Defines endpoint URLs.
+
+- Connects URLs (e.g., `/api/login`) to functions in Controllers.
+- Attaches Middleware (e.g., `requireAuth`).
+
+## `lib/` Folder (Framework Internals)
+
+This part is similar to `node_modules` or the `.next` folder in Next.js. This is the framework engine.
+
+### `lib/core/`
+
+The "Engine" part of the framework.
+
+- `server.ts`: Express App setup.
+- `database.ts`: Prisma Client instance.
+- `redis.ts`: Redis connection.
+- `serializer.ts`: JSON Schema caching logic.
+
+### `lib/middleware/`
+
+Built-in framework middleware.
+
+- `auth.ts`: Check JWT Token.
+- `rateLimit.ts`: Limit request count.
+- `requestLogger.ts`: Log every incoming request.
+
+### `lib/utils/`
+
+Built-in Helper functions.
+
+- `validator.ts`: Laravel-style input validation.
+- `response.ts`: Standard JSON response format (`sendFastSuccess`, `sendError`).
+- `logger.ts`: Logging system (Winston).
+
+## `prisma/` Folder
+
+- `migrations/`: Database change history (SQL files). Do not edit manually.
+- `base.prisma.template`: Header of the database schema (contains db datasource config).
+- `seed.ts`: Script for populating initial data (Data Seeding).
+
+## `scripts/` Folder
+
+"Magic" scripts executed by `npm run`.
+
+- `make-controller.js`: Controller generator.
+- `compile-schema.js`: `.prisma` file merger.
+- `init-project.js`: Initial setup wizard.
+
+---
+
+By understanding this structure, you won't get lost when adding new features or debugging.

package/doc/id/ARCHITECTURE_GUIDE.md

@@ -0,0 +1,73 @@
+# Panduan Arsitektur: Menuju "Framework as a Dependency" (Next.js Style)
+
+Saat ini, Lapeh menggunakan pendekatan **Boilerplate** (seperti Laravel), di mana pengguna mendapatkan seluruh kode sumber (`src/`) dan bertanggung jawab atas `express`, `prisma`, dll.
+
+Untuk mengubahnya menjadi seperti **Next.js** (di mana pengguna hanya menginstall `lapeh` dan `package.json` mereka bersih), kita perlu mengubah arsitektur menjadi **Library**.
+
+## 1. Perbedaan Utama
+
+| Fitur | Boilerplate (Lapeh Saat Ini) | Library (Next.js Style) |
+| :--- | :--- | :--- |
+| **Instalasi** | `git clone` / `npx create-lapeh` | `npm install lapeh` |
+| **package.json** | Banyak dependency (`express`, `cors`, dll) | Sedikit (`lapeh`, `react`) |
+| **Scripts** | Panjang (`nodemon src/index.ts`) | Pendek (`lapeh dev`) |
+| **Core Code** | Terbuka di `src/core/` | Tersembunyi di `node_modules/lapeh` |
+| **Update** | Susah (harus merge manual) | Mudah (`npm update lapeh`) |
+
+## 2. Langkah Implementasi
+
+Saya telah memulai langkah pertama dengan menambahkan **CLI Runner** di `bin/index.js`.
+
+### A. Update CLI (`bin/index.js`) ✅ (Sudah Dilakukan)
+Saya sudah menambahkan command `dev`, `start`, dan `build` ke dalam CLI Lapeh. Ini memungkinkan pengguna menjalankan server tanpa tahu perintah aslinya.
+
+```javascript
+// Contoh penggunaan nanti:
+"scripts": {
+  "dev": "lapeh dev",
+  "build": "lapeh build",
+  "start": "lapeh start"
+}
+```
+
+### B. Struktur Project Pengguna (Target)
+Nantinya, project pengguna Lapeh hanya akan berisi file bisnis mereka:
+
+```text
+my-app/
+├── src/
+│   ├── controllers/
+│   ├── routes/
+│   └── models/
+├── lapeh.config.ts  <-- Konfigurasi framework (pengganti edit core)
+└── package.json
+```
+
+Dan `package.json` mereka akan terlihat seperti ini:
+
+```json
+{
+  "name": "my-app",
+  "dependencies": {
+    "lapeh": "^2.0.0"
+  },
+  "scripts": {
+    "dev": "lapeh dev",
+    "build": "lapeh build",
+    "start": "lapeh start"
+  }
+}
+```
+
+### C. Apa yang Harus Dilakukan Selanjutnya?
+
+1.  **Publish Package**: Anda perlu mempublish folder framework ini ke NPM (atau private registry).
+    *   Pastikan `express`, `cors`, `helmet`, dll ada di `dependencies` (bukan `devDependencies`).
+2.  **Abstraksi `src/index.ts`**:
+    *   Saat ini `src/index.ts` adalah entry point yang diedit user.
+    *   Ubah agar `lapeh dev` menjalankan server internal yang **mengimpor** routes/controller user secara dinamis (seperti Next.js pages router).
+3.  **Config Loader**:
+    *   Buat sistem pembacaan `lapeh.config.ts` untuk mengatur Port, Database URL, dll tanpa mengedit kode core.
+
+## 3. Kesimpulan
+Perubahan yang saya lakukan di `bin/index.js` adalah fondasi untuk CLI style. Untuk mencapai "Clean package.json" sepenuhnya, Anda harus memisahkan **Framework Core** (repo ini) dengan **User Project** (repo baru yang menginstall framework ini).