lapeh 2.2.8 → 2.2.9

package/api-testing-enambelas/doc/STRUCTURE.md

@@ -0,0 +1,90 @@
+# 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.                                                |
+| `lib/`               | **Framework Core**. Bagian internal framework yang jarang Anda sentuh.        |
+| `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 - User Space)
+
+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`).
+
+## Folder `lib/` (Framework Internals)
+
+Bagian ini mirip dengan `node_modules` atau folder `.next` di Next.js. Ini adalah mesin framework.
+
+### `lib/core/`
+
+Bagian "Mesin" framework.
+
+- `server.ts`: Setup Express App.
+- `database.ts`: Instance Prisma Client.
+- `redis.ts`: Koneksi Redis.
+- `serializer.ts`: Logic caching JSON Schema.
+
+### `lib/middleware/`
+
+Middleware bawaan framework.
+
+- `auth.ts`: Cek JWT Token.
+- `rateLimit.ts`: Batasi jumlah request.
+- `requestLogger.ts`: Log setiap request yang masuk.
+
+### `lib/utils/`
+
+Fungsi bantuan (Helper) bawaan.
+
+- `validator.ts`: Validasi input ala Laravel.
+- `response.ts`: Standar format JSON response (`sendFastSuccess`, `sendError`).
+- `logger.ts`: Sistem logging (Winston).
+
+## 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/api-testing-enambelas/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/api-testing-enambelas/docker-compose.yml

@@ -0,0 +1,24 @@
+version: "3.9"
+services:
+  redis:
+    image: redis:7-alpine
+    command: 
+      - "redis-server"
+      - "--appendonly"
+      - "yes"
+      - "--user"
+      - "default on >12341234 ~* +@all"
+      - "--user"
+      - "lapeh on >12341234 ~* +@all"
+    ports:
+      - "6379:6379"
+    volumes:
+      - redis_data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  redis_data:

package/api-testing-enambelas/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/api-testing-enambelas/framework.md

@@ -0,0 +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`
+
+## 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/api-testing-enambelas/nodemon.json

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