lapeh 2.2.1 → 2.2.3

package/doc/STRUCTURE.md

@@ -0,0 +1,72 @@
+# Bedah Struktur Proyek
+
+Untuk memahami Lapeh Framework sepenuhnya, Anda perlu tahu apa fungsi setiap file dan folder. Berikut adalah "Tour" lengkap ke dalam direktori proyek.
+
+## Root Directory
+
+| File/Folder | Deskripsi |
+| :--- | :--- |
+| `bin/` | Berisi script eksekusi untuk CLI (`npx lapeh`). Anda jarang menyentuh ini. |
+| `doc/` | Dokumentasi proyek ini berada. |
+| `prisma/` | Jantung konfigurasi Database. |
+| `scripts/` | Kumpulan script Node.js untuk utility (generator, compiler schema, dll). |
+| `src/` | **Source Code Utama**. 99% kodingan Anda ada di sini. |
+| `.env` | Variabel rahasia (Database URL, API Keys). **Jangan commit file ini ke Git!** |
+| `docker-compose.yml` | Konfigurasi Docker untuk menjalankan Database & Redis lokal. |
+| `nodemon.json` | Konfigurasi auto-restart saat development. |
+| `package.json` | Daftar library (dependencies) dan perintah (`npm run ...`). |
+| `tsconfig.json` | Konfigurasi TypeScript. |
+
+## Folder `src/` (Source Code)
+
+Ini adalah tempat Anda bekerja setiap hari.
+
+### `src/controllers/`
+Berisi logika aplikasi. Controller menerima Request, memprosesnya, dan mengembalikan Response.
+- **Contoh**: `authController.ts` menangani login/register.
+- **Tips**: Jangan taruh *business logic* yang terlalu kompleks di sini. Gunakan Service (opsional) jika controller sudah terlalu gemuk.
+
+### `src/models/`
+Berisi definisi tabel database (Schema Prisma).
+- **Unik di Lapeh**: Kami memecah `schema.prisma` yang besar menjadi file-file kecil per fitur (misal `user.prisma`, `product.prisma`) agar mudah di-manage. Script `prisma:migrate` akan menggabungkannya nanti.
+
+### `src/routes/`
+Mendefinisikan URL endpoint.
+- Menghubungkan URL (misal `/api/login`) ke fungsi di Controller.
+- Menempelkan Middleware (misal `requireAuth`).
+
+### `src/middleware/`
+Kode yang berjalan *sebelum* Controller.
+- `auth.ts`: Cek JWT Token.
+- `rateLimit.ts`: Batasi jumlah request.
+- `requestLogger.ts`: Log setiap request yang masuk.
+
+### `src/utils/`
+Fungsi bantuan (Helper) yang bisa dipakai di mana saja.
+- `validator.ts`: Validasi input ala Laravel.
+- `response.ts`: Standar format JSON response (`sendSuccess`, `sendError`).
+- `logger.ts`: Sistem logging (Winston).
+
+### `src/core/`
+Bagian "Mesin" framework. Anda jarang perlu mengubah ini kecuali ingin memodifikasi behavior dasar framework.
+- `server.ts`: Setup Express App.
+- `database.ts`: Instance Prisma Client.
+- `redis.ts`: Koneksi Redis.
+- `serializer.ts`: Logic caching JSON Schema.
+
+## Folder `prisma/`
+
+- `migrations/`: History perubahan database (SQL file). Jangan diedit manual.
+- `base.prisma.template`: Header dari schema database (berisi konfigurasi datasource db).
+- `seed.ts`: Script untuk mengisi data awal (Data Seeding).
+
+## Folder `scripts/`
+
+Script-script "Magic" yang dijalankan `npm run`.
+- `make-controller.js`: Generator controller.
+- `compile-schema.js`: Penggabung file `.prisma`.
+- `init-project.js`: Wizard setup awal.
+
+---
+
+Dengan memahami struktur ini, Anda tidak akan tersesat saat ingin menambah fitur baru atau mencari bug.

package/doc/TUTORIAL.md

@@ -0,0 +1,192 @@
+# Tutorial: Membangun API Perpustakaan
+
+Dalam tutorial ini, kita akan membangun fitur "Manajemen Buku" sederhana menggunakan semua fitur unggulan Lapeh Framework:
+1.  **CLI** untuk generate kode.
+2.  **Validator** untuk validasi input.
+3.  **Fast Serialization** untuk respon cepat.
+4.  **RBAC** untuk proteksi delete (Admin only).
+
+## Langkah 1: Generate Model Database
+
+Kita butuh tabel `books`. Gunakan CLI `make:model`.
+
+```bash
+npm run make:model Book
+```
+
+File baru akan muncul di `src/models/book.prisma`. Edit file tersebut:
+
+```prisma
+// src/models/book.prisma
+
+model Book {
+  id          BigInt   @id @default(autoincrement())
+  title       String
+  author      String
+  isbn        String   @unique
+  publishedAt DateTime
+  stock       Int      @default(0)
+  created_at  DateTime @default(now())
+  updated_at  DateTime @updatedAt
+
+  @@map("books")
+}
+```
+
+Terapkan perubahan ke database:
+
+```bash
+npm run prisma:migrate
+```
+
+## Langkah 2: Generate Module (Controller & Route)
+
+Kita buat controller dan route sekaligus.
+
+```bash
+npm run make:module Book
+```
+
+Framework akan membuat:
+- `src/controllers/bookController.ts`
+- `src/routes/book.ts`
+
+## Langkah 3: Implementasi Controller
+
+Buka `src/controllers/bookController.ts` dan kita implementasikan fitur **Create** dan **List** dengan standar framework.
+
+### Setup Import & Serializer
+
+```typescript
+import { Request, Response } from "express";
+import { prisma } from "@/core/database";
+import { sendFastSuccess, sendError } from "@/utils/response";
+import { Validator } from "@/utils/validator";
+import { getSerializer, createResponseSchema } from "@/core/serializer";
+
+// 1. Definisikan Schema Output (untuk Fastify Serialization)
+const bookSchema = {
+  type: "object",
+  properties: {
+    id: { type: "string" }, // BigInt -> String
+    title: { type: "string" },
+    author: { type: "string" },
+    isbn: { type: "string" },
+    stock: { type: "number" }
+  }
+};
+
+// 2. Buat Serializer
+const bookDetailSerializer = getSerializer("book-detail", createResponseSchema(bookSchema));
+const bookListSerializer = getSerializer("book-list", createResponseSchema({
+  type: "array",
+  items: bookSchema
+}));
+```
+
+### Implementasi Create (dengan Validasi)
+
+```typescript
+export async function createBook(req: Request, res: Response) {
+  // 1. Validasi Input
+  const validator = await Validator.make(req.body, {
+    title: "required|string|min:3",
+    author: "required|string",
+    isbn: "required|string|unique:books,isbn", // Cek unik di tabel books
+    stock: "required|number|min:1",
+    publishedAt: "required|string" // Format tanggal ISO
+  });
+
+  if (validator.fails()) {
+    return sendError(res, 400, "Validation Error", validator.errors());
+  }
+
+  const data = validator.validated();
+
+  // 2. Simpan ke Database
+  const book = await prisma.book.create({
+    data: {
+      title: data.title,
+      author: data.author,
+      isbn: data.isbn,
+      stock: data.stock,
+      publishedAt: new Date(data.publishedAt)
+    }
+  });
+
+  // 3. Return Response Cepat
+  return sendFastSuccess(res, 201, bookDetailSerializer, {
+    status: "success",
+    message: "Buku berhasil ditambahkan",
+    data: { ...book, id: book.id.toString() } // Konversi BigInt manual jika perlu
+  });
+}
+```
+
+### Implementasi List (High Performance)
+
+```typescript
+export async function getBooks(req: Request, res: Response) {
+  const books = await prisma.book.findMany({
+    take: 50, // Limit 50
+    orderBy: { created_at: "desc" }
+  });
+
+  // Convert BigInt to string sebelum passing ke serializer (opsional, tapi aman)
+  const safeBooks = books.map(b => ({ ...b, id: b.id.toString() }));
+
+  return sendFastSuccess(res, 200, bookListSerializer, {
+    status: "success",
+    message: "Daftar buku",
+    data: safeBooks
+  });
+}
+```
+
+## Langkah 4: Daftarkan Route & Proteksi
+
+Buka `src/routes/book.ts` (atau file yang digenerate). Pastikan route terhubung dan tambahkan middleware auth.
+
+```typescript
+import { Router } from "express";
+import { createBook, getBooks } from "../controllers/bookController";
+import { requireAuth, requireAdmin } from "../middleware/auth";
+
+export const bookRouter = Router();
+
+// Public route (bisa diakses siapa saja)
+bookRouter.get("/", getBooks);
+
+// Admin only (Butuh login + role admin)
+bookRouter.post("/", requireAuth, requireAdmin, createBook);
+```
+
+Terakhir, daftarkan router ini di `src/routes/index.ts` (jika belum otomatis):
+
+```typescript
+import { bookRouter } from "./book";
+// ...
+router.use("/books", bookRouter);
+```
+
+## Langkah 5: Testing
+
+Jalankan server:
+```bash
+npm run dev
+```
+
+Coba hit endpoint:
+1. **POST /api/books** (Tanpa token) -> 401 Unauthorized.
+2. **POST /api/books** (Token User Biasa) -> 403 Forbidden.
+3. **POST /api/books** (Token Admin + Data Invalid) -> 400 Validation Error.
+4. **POST /api/books** (Token Admin + Data Valid) -> 201 Created.
+5. **GET /api/books** -> 200 OK (Super Cepat).
+
+## Kesimpulan
+
+Dengan Lapeh Framework, Anda telah membuat API yang:
+- **Aman** (Validasi, Auth, RBAC).
+- **Cepat** (Fast Serialization).
+- **Rapi** (Struktur terstandarisasi).
+- **Mudah** (CLI Generator).

package/eslint.config.mjs

@@ -0,0 +1,26 @@
+import globals from "globals";
+import pluginJs from "@eslint/js";
+import tseslint from "typescript-eslint";
+
+export default [
+  { files: ["**/*.{js,mjs,cjs,ts}"] },
+  { languageOptions: { globals: globals.node } },
+  pluginJs.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    rules: {
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        {
+          "argsIgnorePattern": "^_",
+          "varsIgnorePattern": "^_",
+          "caughtErrorsIgnorePattern": "^_"
+        }
+      ],
+      "@typescript-eslint/no-explicit-any": "warn"
+    }
+  },
+  {
+    ignores: ["dist/", "node_modules/", "generated/", "scripts/"]
+  }
+];

package/framework.md

@@ -1,113 +1,168 @@
-# Lapeh Framework
-
-## Quick Start
-
-Untuk memulai project ini (Setup awal):
-
-```bash
-npm i
-```
-
-```bash
-npm run first
-```
-
-Perintah di atas akan secara otomatis melakukan:
-
-1. Copy `.env.example` ke `.env`
-2. Install dependencies (`npm install`)
-3. Generate JWT Secret baru di `.env`
-4. Setup database (Migrate)
-5. Menjalankan Database Seeder
-
-Setelah selesai, Anda bisa langsung menjalankan project:
-
-```bash
-npm run dev
-```
-
-### Akun Default
-
-Jika seeder dijalankan (via `npm run first` atau `npm run db:seed`), gunakan akun berikut:
-
-- **Super Admin**: `sa@sa.com` / `string`
-- **Admin**: `a@a.com` / `string`
-- **User**: `u@u.com` / `string`
-
-## Database Workflow (Prisma)
-
-Framework ini menggunakan **Prisma ORM** dengan struktur schema yang modular (dipecah per file). Berikut adalah panduan lengkap dari Development hingga Deployment.
-
-### 1. Development (Lokal)
-
-Saat mengembangkan aplikasi di local environment:
-
-**a. Mengupdate Schema Database**
-Jika Anda mengubah file schema di `src/models/*.prisma` atau konfigurasi di `prisma/base.prisma.template`:
-
-```bash
-npm run prisma:migrate
-```
-
-_Perintah ini akan menggabungkan semua file schema, membuat file migrasi baru, menerapkan ke database lokal, dan men-generate ulang Prisma Client._
-
-**b. Melihat/Edit Data (GUI)**
-Untuk membuka dashboard visual database:
-
-```bash
-npm run db:studio
-```
-
-**c. Mengisi Data Awal (Seeding)**
-Jika Anda butuh data dummy atau data awal (seperti roles/permissions):
-
-```bash
-npm run db:seed
-```
-
-**d. Reset Database Total**
-Jika database berantakan dan ingin mengulang dari awal (HATI-HATI: Menghapus semua data):
-
-```bash
-npm run db:reset
-```
-
-_Perintah ini akan menghapus database, membuat ulang schema dari awal, dan otomatis menjalankan seeder._
-
----
-
-### 2. Deployment (Production)
-
-Saat deploy ke server production:
-
-**a. Setup Awal**
-Pastikan `.env` di production sudah disetup dengan benar (DATABASE_URL, dll).
-
-**b. Menerapkan Migrasi**
-Jangan gunakan `migrate dev` di production. Gunakan perintah ini:
-
-```bash
-npm run prisma:deploy
-```
-
-_Perintah ini hanya akan menerapkan file migrasi yang sudah ada ke database production tanpa mereset data atau meminta konfirmasi interaktif._
-
-**c. Generate Client (Opsional)**
-Biasanya dilakukan otomatis saat `npm install` (karena `postinstall`), tapi jika perlu manual:
-
-```bash
-npm run prisma:generate
-```
-
----
-
-### Ringkasan Command
-
-| Command                   | Fungsi                                                   | Environment  |
-| ------------------------- | -------------------------------------------------------- | ------------ |
-| `npm run prisma:migrate`  | Compile schema + Create Migration + Apply to DB          | **Dev**      |
-| `npm run prisma:deploy`   | Compile schema + Apply Migration only                    | **Prod**     |
-| `npm run prisma:generate` | Compile schema + Update Prisma Client (Type Definitions) | Dev/Prod     |
-| `npm run db:seed`         | Menjalankan script `prisma/seed.ts`                      | Dev/Prod     |
-| `npm run db:reset`        | Hapus DB + Migrate ulang + Seed                          | **Dev Only** |
-| `npm run db:studio`       | Buka GUI database di browser                             | Dev          |
+# Lapeh Framework
+
+## Quick Start
+
+Untuk memulai project ini (Setup awal):
+
+```bash
+npm i
+```
+
+```bash
+npm run first
+```
+
+Perintah di atas akan secara otomatis melakukan:
+
+1. Copy `.env.example` ke `.env`
+2. Install dependencies (`npm install`)
+3. Generate JWT Secret baru di `.env`
+4. Setup database (Migrate)
+5. Menjalankan Database Seeder
+
+Setelah selesai, Anda bisa langsung menjalankan project:
+
+```bash
+npm run dev
+```
+
+### Akun Default
+
+Jika seeder dijalankan (via `npm run first` atau `npm run db:seed`), gunakan akun berikut:
+
+- **Super Admin**: `sa@sa.com` / `string`
+- **Admin**: `a@a.com` / `string`
+- **User**: `u@u.com` / `string`
+
+## Code Standards & Best Practices (Baru)
+
+### 1. Import Path Aliases
+Gunakan alias `@/` untuk mengimpor module dari folder `src/`. Hindari relative path yang panjang seperti `../../utils/response`.
+
+**Contoh:**
+```typescript
+// ✅ Benar (Recommended)
+import { prisma } from "@/core/database";
+import { sendSuccess } from "@/utils/response";
+
+// ❌ Salah (Legacy)
+import { prisma } from "../core/database";
+import { sendSuccess } from "../../utils/response";
+```
+
+### 2. Strict Linting (Dead Code Elimination)
+Framework ini menerapkan aturan linter yang ketat untuk menjaga kebersihan kode. Variabel, parameter, atau import yang tidak digunakan akan menyebabkan error.
+
+- **Variabel tidak terpakai**: Hapus atau beri prefix `_` (underscore).
+  ```typescript
+  // ✅ Benar
+  const _unusedVariable = 123;
+  function example(_req: Request, res: Response) { ... }
+  
+  // ❌ Error
+  const unusedVariable = 123;
+  function example(req: Request, res: Response) { ... } // jika req tidak dipakai
+  ```
+
+### 3. High Performance Response (Fastify-Style)
+Untuk endpoint dengan throughput tinggi (GET lists, data besar), gunakan `sendFastSuccess` dengan JSON Schema serializer. Ini 2-3x lebih cepat dari `res.json` standar Express.
+
+**Langkah-langkah:**
+
+1. **Definisikan Schema** (sesuai field Prisma):
+   ```typescript
+   const userSchema = {
+     type: "object",
+     properties: {
+       id: { type: "string" }, // BigInt otomatis dicovert ke string
+       name: { type: "string" },
+       email: { type: "string" }
+     }
+   };
+   ```
+
+2. **Buat Serializer**:
+   ```typescript
+   import { getSerializer, createResponseSchema } from "@/core/serializer";
+   
+   const userSerializer = getSerializer("user-detail", createResponseSchema(userSchema));
+   ```
+
+3. **Gunakan di Controller**:
+   ```typescript
+   import { sendFastSuccess } from "@/utils/response";
+   
+   export async function getUser(req, res) {
+     const user = await prisma.user.findFirst();
+     sendFastSuccess(res, 200, userSerializer, {
+       status: "success",
+       message: "User found",
+       data: user
+     });
+   }
+   ```
+
+## Database Workflow (Prisma)
+
+Framework ini menggunakan **Prisma ORM** dengan struktur schema yang modular (dipecah per file). Berikut adalah panduan lengkap dari Development hingga Deployment.
+
+### 1. Development (Lokal)
+
+Saat mengembangkan aplikasi di local environment:
+
+**a. Mengupdate Schema Database**
+Jika Anda mengubah file schema di `src/models/*.prisma` atau konfigurasi di `prisma/base.prisma.template`:
+
+```bash
+npm run prisma:migrate
+```
+
+_Perintah ini akan menggabungkan semua file schema, membuat file migrasi baru, menerapkan ke database lokal, dan men-generate ulang Prisma Client._
+
+**b. Melihat/Edit Data (GUI)**
+Untuk membuka dashboard visual database:
+
+```bash
+npm run db:studio
+```
+
+**c. Mengisi Data Awal (Seeding)**
+Jika Anda butuh data dummy atau data awal (seperti roles/permissions):
+
+```bash
+npm run db:seed
+```
+
+**d. Reset Database Total**
+Jika database berantakan dan ingin mengulang dari awal (HATI-HATI: Menghapus semua data):
+
+```bash
+npm run db:reset
+```
+
+_Perintah ini akan menghapus database, membuat ulang schema dari awal, dan otomatis menjalankan seeder._
+
+---
+
+### 2. Deployment (Production)
+
+Saat deploy ke server production:
+
+**a. Setup Awal**
+Pastikan `.env` di production sudah disetup dengan benar (DATABASE_URL, dll).
+
+**b. Menerapkan Migrasi**
+Jangan gunakan `migrate dev` di production. Gunakan perintah ini:
+
+```bash
+npm run prisma:deploy
+```
+
+_Perintah ini hanya akan menerapkan file migrasi yang sudah ada ke database production tanpa mereset data atau meminta konfirmasi interaktif._
+
+**c. Generate Client (Opsional)**
+Biasanya dilakukan otomatis saat `npm install` (karena `postinstall`), tapi jika perlu manual:
+
+```bash
+npm run prisma:generate
+```

package/nodemon.json

@@ -2,5 +2,5 @@
   "watch": ["src", ".env"],
   "ext": "ts,json",
   "ignore": ["src/**/*.test.ts"],
-  "exec": "ts-node src/index.ts"
+  "exec": "ts-node -r tsconfig-paths/register src/index.ts"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lapeh",
-  "version": "2.2.1",
+  "version": "2.2.3",
   "description": "Framework API Express yang siap pakai (Standardized)",
   "main": "index.js",
   "bin": {
@@ -19,12 +19,14 @@
     "dev": "node scripts/check-update.js && nodemon src/index.ts",
     "first": "node scripts/init-project.js",
     "prebuild": "npm run prisma:generate",
-    "build": "tsc",
+    "build": "tsc && tsc-alias",
     "prestart": "npm run prisma:generate",
     "start": "node dist/src/index.js",
     "prestart:prod": "npm run prisma:generate",
     "start:prod": "NODE_ENV=production node dist/src/index.js",
     "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
     "prisma:generate": "node scripts/compile-schema.js && prisma generate",
     "prisma:migrate": "node scripts/compile-schema.js && prisma migrate dev",
     "prisma:deploy": "node scripts/compile-schema.js && prisma migrate deploy",
@@ -69,6 +71,7 @@
     "dotenv": "17.2.3",
     "express": "5.2.1",
     "express-rate-limit": "8.2.1",
+    "fast-json-stringify": "^6.1.1",
     "helmet": "8.1.0",
     "ioredis": "5.8.2",
     "ioredis-mock": "^8.13.1",
@@ -83,6 +86,7 @@
     "zod": "3.23.8"
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.2",
     "@types/bcryptjs": "2.4.6",
     "@types/cors": "2.8.19",
     "@types/express": "5.0.6",
@@ -91,9 +95,14 @@
     "@types/node": "25.0.3",
     "@types/pg": "8.16.0",
     "@types/uuid": "10.0.0",
+    "eslint": "^9.39.2",
+    "globals": "^16.5.0",
     "nodemon": "3.1.11",
     "prisma": "7.2.0",
     "ts-node": "10.9.2",
-    "typescript": "5.9.3"
+    "tsc-alias": "^1.8.16",
+    "tsconfig-paths": "^4.2.0",
+    "typescript": "5.9.3",
+    "typescript-eslint": "^8.50.1"
   }
 }

package/prisma/seed.ts

@@ -1,7 +1,6 @@
 import { prisma } from "../src/core/database";
 import bcrypt from "bcryptjs";
 import { v4 as uuidv4 } from "uuid";
-import slugify from "slugify";
 
 async function main() {
   console.log("Start seeding...");