lapeh 2.2.1 → 2.2.3

package/readme.md

@@ -14,6 +14,46 @@ Cocok untuk developer yang mencari **Express boilerplate** dengan fitur lengkap:
 - **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)
+
+Lapeh 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)
+
+Lapeh 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
 
@@ -251,6 +291,7 @@ MIT
 ## 🚀 Deployment Guide
 
 ### 1) Build & Generate Prisma Client (Otomatis)
+
 - Build: `npm run build`
 - Start (dev): `npm run start`
 - Start (prod): `npm run start:prod`
@@ -258,6 +299,7 @@ MIT
   - `prebuild`, `prestart`, dan `prestart:prod` akan memanggil `npm run prisma:generate` sehingga Prisma Client selalu tersedia tanpa error.
 
 ### 2) Production Environment
+
 - Pastikan `.env` berisi kredensial production:
   - `DATABASE_URL` dan `DATABASE_PROVIDER` (mysql/postgresql)
   - `JWT_SECRET` (gunakan `npm run generate:jwt` untuk mengganti)
@@ -268,6 +310,7 @@ npm run prisma:deploy
 ```
 
 ### 3) Menjalankan dengan PM2
+
 - Install PM2:
 
 ```bash
@@ -296,6 +339,7 @@ pm2 restart lapeh-api
 ```
 
 ### 4) Nginx Reverse Proxy (Recommended)
+
 - Buat server block `/etc/nginx/sites-available/lapeh`:
 
 ```nginx
@@ -329,6 +373,7 @@ sudo certbot --nginx -d example.com
 ```
 
 ### 5) Apache 2 Reverse Proxy (Alternatif)
+
 - Enable modul proxy:
 
 ```bash
@@ -362,6 +407,7 @@ sudo systemctl reload apache2
 ```
 
 ### 6) Checklist Produksi
+
 - `npm run prisma:deploy` sukses dan tabel terbentuk
 - `pm2 status` menunjukkan proses hidup
 - Proxy (Nginx/Apache) menuju port aplikasi (default 4000)

package/src/controllers/authController.ts

@@ -1,13 +1,83 @@
-import { Request, Response } from "express";
-import bcrypt from "bcryptjs";
-import jwt from "jsonwebtoken";
-import { v4 as uuidv4 } from "uuid";
-import { prisma } from "../core/database";
-import { sendSuccess, sendError } from "../utils/response";
-import { Validator } from "../utils/validator";
+import { Request, Response } from "express";
+import bcrypt from "bcryptjs";
+import jwt from "jsonwebtoken";
+import { v4 as uuidv4 } from "uuid";
+import { prisma } from "@/core/database";
+import { sendSuccess, sendError, sendFastSuccess } from "@/utils/response";
+import { Validator } from "@/utils/validator";
+import { getSerializer, createResponseSchema } from "@/core/serializer";
 
 export const ACCESS_TOKEN_EXPIRES_IN_SECONDS = 7 * 24 * 60 * 60;
 
+// --- Serializers ---
+
+const registerSchema = {
+  type: "object",
+  properties: {
+    id: { type: "string" },
+    email: { type: "string" },
+    name: { type: "string" },
+    role: { type: "string" },
+  },
+};
+
+const loginSchema = {
+  type: "object",
+  properties: {
+    token: { type: "string" },
+    refreshToken: { type: "string" },
+    expiresIn: { type: "integer" },
+    expiresAt: { type: "string" },
+    name: { type: "string" },
+    role: { type: "string" },
+  },
+};
+
+const userProfileSchema = {
+  type: "object",
+  properties: {
+    id: { type: "string" },
+    name: { type: "string" },
+    email: { type: "string" },
+    role: { type: "string" },
+    avatar: { type: "string", nullable: true },
+    avatar_url: { type: "string", nullable: true },
+    email_verified_at: { type: "string", format: "date-time", nullable: true },
+    created_at: { type: "string", format: "date-time", nullable: true },
+    updated_at: { type: "string", format: "date-time", nullable: true },
+  },
+};
+
+const refreshTokenSchema = {
+  type: "object",
+  properties: {
+    token: { type: "string" },
+    expiresIn: { type: "integer" },
+    expiresAt: { type: "string" },
+    name: { type: "string" },
+    role: { type: "string" },
+  },
+};
+
+const registerSerializer = getSerializer(
+  "auth-register",
+  createResponseSchema(registerSchema)
+);
+const loginSerializer = getSerializer(
+  "auth-login",
+  createResponseSchema(loginSchema)
+);
+const userProfileSerializer = getSerializer(
+  "auth-profile",
+  createResponseSchema(userProfileSchema)
+);
+const refreshTokenSerializer = getSerializer(
+  "auth-refresh",
+  createResponseSchema(refreshTokenSchema)
+);
+
+// --- Controllers ---
+
 export async function register(req: Request, res: Response) {
   const validator = Validator.make(req.body || {}, {
     email: "required|email|unique:users,email",
@@ -47,11 +117,15 @@ export async function register(req: Request, res: Response) {
     });
   }
 
-  sendSuccess(res, 200, "Registration successful", {
-    id: user.id.toString(),
-    email: user.email,
-    name: user.name,
-    role: defaultRole ? defaultRole.slug : "user",
+  sendFastSuccess(res, 200, registerSerializer, {
+    status: "success",
+    message: "Registration successful",
+    data: {
+      id: user.id.toString(),
+      email: user.email,
+      name: user.name,
+      role: defaultRole ? defaultRole.slug : "user",
+    },
   });
 }
 
@@ -119,13 +193,17 @@ export async function login(req: Request, res: Response) {
     secret,
     { expiresIn: refreshExpiresInSeconds }
   );
-  sendSuccess(res, 200, "Login successful", {
-    token,
-    refreshToken,
-    expiresIn: accessExpiresInSeconds,
-    expiresAt: accessExpiresAt,
-    name: user.name,
-    role: primaryUserRole,
+  sendFastSuccess(res, 200, loginSerializer, {
+    status: "success",
+    message: "Login successful",
+    data: {
+      token,
+      refreshToken,
+      expiresIn: accessExpiresInSeconds,
+      expiresAt: accessExpiresAt,
+      name: user.name,
+      role: primaryUserRole,
+    },
   });
 }
 
@@ -150,17 +228,24 @@ export async function me(req: Request, res: Response) {
     return;
   }
   const { password, remember_token, ...rest } = user as any;
-  sendSuccess(res, 200, "User profile", {
-    ...rest,
-    id: user.id.toString(),
-    role:
-      user.user_roles && user.user_roles.length > 0 && user.user_roles[0].role
-        ? user.user_roles[0].role.slug
-        : "user",
+  sendFastSuccess(res, 200, userProfileSerializer, {
+    status: "success",
+    message: "User profile",
+    data: {
+      ...rest,
+      id: user.id.toString(),
+      role:
+        user.user_roles && user.user_roles.length > 0 && user.user_roles[0].role
+          ? user.user_roles[0].role.slug
+          : "user",
+    },
   });
 }
 
-export async function logout(req: Request, res: Response) {
+export async function logout(_req: Request, res: Response) {
+  // In a stateless JWT setup, logout is client-side (delete token).
+  // If using a whitelist/blacklist in Redis, invalidate the token here.
+  // For now, just return success.
   sendSuccess(res, 200, "Logout successful", null);
 }
 
@@ -217,12 +302,16 @@ export async function refreshToken(req: Request, res: Response) {
       secret,
       { expiresIn: accessExpiresInSeconds }
     );
-    sendSuccess(res, 200, "Token refreshed", {
-      token,
-      expiresIn: accessExpiresInSeconds,
-      expiresAt: accessExpiresAt,
-      name: user.name,
-      role: primaryUserRole,
+    sendFastSuccess(res, 200, refreshTokenSerializer, {
+      status: "success",
+      message: "Token refreshed",
+      data: {
+        token,
+        expiresIn: accessExpiresInSeconds,
+        expiresAt: accessExpiresAt,
+        name: user.name,
+        role: primaryUserRole,
+      },
     });
   } catch {
     sendError(res, 401, "Invalid refresh token");
@@ -268,9 +357,21 @@ export async function updateAvatar(req: Request, res: Response) {
     },
   });
   const { password, remember_token, ...rest } = updated as any;
-  sendSuccess(res, 200, "Avatar updated successfully", {
-    ...rest,
-    id: updated.id.toString(),
+  // Note: user_roles might not be fetched in update, so role defaults to "user" or fetched if needed.
+  // Ideally we should refetch or pass existing role.
+  // For now assuming role is preserved or handled by frontend state, but API should return it.
+  // Let's rely on nullable role or simple "user" fallback if not present in `updated`.
+  // Actually `update` returns what was updated. Relations are not included unless specified.
+  // For now we will return it compatible with userProfileSchema.
+
+  sendFastSuccess(res, 200, userProfileSerializer, {
+    status: "success",
+    message: "Avatar updated successfully",
+    data: {
+      ...rest,
+      id: updated.id.toString(),
+      role: payload.role, // Use role from JWT payload as it shouldn't change here
+    },
   });
 }
 
@@ -343,8 +444,13 @@ export async function updateProfile(req: Request, res: Response) {
     },
   });
   const { password, remember_token, ...rest } = updated as any;
-  sendSuccess(res, 200, "Profile updated successfully", {
-    ...rest,
-    id: updated.id.toString(),
+  sendFastSuccess(res, 200, userProfileSerializer, {
+    status: "success",
+    message: "Profile updated successfully",
+    data: {
+      ...rest,
+      id: updated.id.toString(),
+      role: payload.role, // Use role from JWT payload
+    },
   });
 }

package/src/controllers/petController.ts

@@ -1,8 +1,39 @@
 import { Request, Response } from "express";
-import { prisma } from "../core/database";
-import { sendSuccess, sendError } from "../utils/response";
-import { getPagination, buildPaginationMeta } from "../utils/pagination";
-import { Validator } from "../utils/validator";
+import { prisma } from "@/core/database";
+import { sendSuccess, sendError, sendFastSuccess } from "@/utils/response";
+import { getPagination, buildPaginationMeta } from "@/utils/pagination";
+import { Validator } from "@/utils/validator";
+import {
+  getSerializer,
+  createResponseSchema,
+  createPaginatedResponseSchema,
+} from "@/core/serializer";
+
+// 1. Definisikan Schema Output untuk performa tinggi
+const petSchema = {
+  type: "object",
+  properties: {
+    id: { type: "string" }, // BigInt dikonversi ke string
+    name: { type: "string" },
+    species: { type: "string" },
+    age: { type: "integer" },
+    created_at: { type: "string", format: "date-time" },
+    updated_at: { type: "string", format: "date-time" },
+  },
+};
+
+// 2. Compile Serializer
+// Untuk Single Item
+const petSerializer = getSerializer(
+  "pet-single",
+  createResponseSchema(petSchema)
+);
+
+// Untuk List Item (Paginated)
+const petListSerializer = getSerializer(
+  "pet-list",
+  createPaginatedResponseSchema(petSchema)
+);
 
 export async function index(req: Request, res: Response) {
   const { page, perPage, skip, take } = getPagination(req.query);
@@ -26,6 +57,8 @@ export async function index(req: Request, res: Response) {
     prisma.pets.count({ where }),
   ]);
 
+  // Kita perlu convert BigInt ke string sebelum masuk serializer
+  // Karena fast-json-stringify mengharapkan tipe data yang sesuai dengan schema
   const serialized = data.map((item: any) => ({
     ...item,
     id: item.id.toString(),
@@ -33,9 +66,15 @@ export async function index(req: Request, res: Response) {
 
   const meta = buildPaginationMeta(page, perPage, total);
 
-  sendSuccess(res, 200, "Pets retrieved successfully", {
-    data: serialized,
-    meta,
+  // Gunakan sendFastSuccess untuk performa maksimal
+  // Struktur data disesuaikan dengan createPaginatedResponseSchema: { data: [], meta: {} }
+  sendFastSuccess(res, 200, petListSerializer, {
+    status: "success",
+    message: "Pets retrieved successfully",
+    data: {
+      data: serialized,
+      meta,
+    },
   });
 }
 
@@ -50,9 +89,14 @@ export async function show(req: Request, res: Response) {
     return;
   }
 
-  sendSuccess(res, 200, "Pet retrieved successfully", {
-    ...pet,
-    id: pet.id.toString(),
+  // Gunakan sendFastSuccess
+  sendFastSuccess(res, 200, petSerializer, {
+    status: "success",
+    message: "Pet retrieved successfully",
+    data: {
+      ...pet,
+      id: pet.id.toString(),
+    },
   });
 }
 
@@ -77,9 +121,14 @@ export async function store(req: Request, res: Response) {
     },
   });
 
-  sendSuccess(res, 201, "Pet created successfully", {
-    ...pet,
-    id: pet.id.toString(),
+  // Gunakan sendFastSuccess
+  sendFastSuccess(res, 201, petSerializer, {
+    status: "success",
+    message: "Pet created successfully",
+    data: {
+      ...pet,
+      id: pet.id.toString(),
+    },
   });
 }
 
@@ -114,9 +163,14 @@ export async function update(req: Request, res: Response) {
     },
   });
 
-  sendSuccess(res, 200, "Pet updated successfully", {
-    ...updated,
-    id: updated.id.toString(),
+  // Gunakan sendFastSuccess
+  sendFastSuccess(res, 200, petSerializer, {
+    status: "success",
+    message: "Pet updated successfully",
+    data: {
+      ...updated,
+      id: updated.id.toString(),
+    },
   });
 }
 

package/src/controllers/rbacController.ts

@@ -1,8 +1,52 @@
 import { Request, Response } from "express";
-import { prisma } from "../core/database";
-import { sendSuccess, sendError } from "../utils/response";
-import { Validator } from "../utils/validator";
+import { prisma } from "@/core/database";
+import { sendSuccess, sendError, sendFastSuccess } from "@/utils/response";
+import { Validator } from "@/utils/validator";
 import { z } from "zod";
+import { getSerializer, createResponseSchema } from "@/core/serializer";
+
+// --- Serializers ---
+
+const roleSchema = {
+  type: "object",
+  properties: {
+    id: { type: "string" },
+    name: { type: "string" },
+    slug: { type: "string" },
+    description: { type: "string", nullable: true },
+    created_at: { type: "string", format: "date-time", nullable: true },
+    updated_at: { type: "string", format: "date-time", nullable: true },
+  },
+};
+
+const permissionSchema = {
+  type: "object",
+  properties: {
+    id: { type: "string" },
+    name: { type: "string" },
+    slug: { type: "string" },
+    description: { type: "string", nullable: true },
+    created_at: { type: "string", format: "date-time", nullable: true },
+    updated_at: { type: "string", format: "date-time", nullable: true },
+  },
+};
+
+const roleSerializer = getSerializer("role", createResponseSchema(roleSchema));
+const roleListSerializer = getSerializer(
+  "role-list",
+  createResponseSchema({ type: "array", items: roleSchema })
+);
+
+const permissionSerializer = getSerializer(
+  "permission",
+  createResponseSchema(permissionSchema)
+);
+const permissionListSerializer = getSerializer(
+  "permission-list",
+  createResponseSchema({ type: "array", items: permissionSchema })
+);
+
+// --- Controllers ---
 
 export async function createRole(req: Request, res: Response) {
   const validator = Validator.make(req.body || {}, {
@@ -28,14 +72,23 @@ export async function createRole(req: Request, res: Response) {
       updated_at: new Date(),
     },
   });
-  sendSuccess(res, 201, "Role created", role);
+  sendFastSuccess(res, 201, roleSerializer, {
+    status: "success",
+    message: "Role created",
+    data: { ...role, id: role.id.toString() },
+  });
 }
 
 export async function listRoles(_req: Request, res: Response) {
   const roles = await prisma.roles.findMany({
     orderBy: { id: "asc" },
   });
-  sendSuccess(res, 200, "Roles list", roles);
+  const serialized = roles.map((r: any) => ({ ...r, id: r.id.toString() }));
+  sendFastSuccess(res, 200, roleListSerializer, {
+    status: "success",
+    message: "Roles list",
+    data: serialized,
+  });
 }
 
 export async function updateRole(req: Request, res: Response) {
@@ -69,7 +122,11 @@ export async function updateRole(req: Request, res: Response) {
       updated_at: new Date(),
     },
   });
-  sendSuccess(res, 200, "Role updated", updated);
+  sendFastSuccess(res, 200, roleSerializer, {
+    status: "success",
+    message: "Role updated",
+    data: { ...updated, id: updated.id.toString() },
+  });
 }
 
 export async function deleteRole(req: Request, res: Response) {
@@ -109,14 +166,26 @@ export async function createPermission(req: Request, res: Response) {
       updated_at: new Date(),
     },
   });
-  sendSuccess(res, 201, "Permission created", permission);
+  sendFastSuccess(res, 201, permissionSerializer, {
+    status: "success",
+    message: "Permission created",
+    data: { ...permission, id: permission.id.toString() },
+  });
 }
 
 export async function listPermissions(_req: Request, res: Response) {
   const permissions = await prisma.permissions.findMany({
     orderBy: { id: "asc" },
   });
-  sendSuccess(res, 200, "Permissions list", permissions);
+  const serialized = permissions.map((p: any) => ({
+    ...p,
+    id: p.id.toString(),
+  }));
+  sendFastSuccess(res, 200, permissionListSerializer, {
+    status: "success",
+    message: "Permissions list",
+    data: serialized,
+  });
 }
 
 export async function updatePermission(req: Request, res: Response) {
@@ -152,7 +221,11 @@ export async function updatePermission(req: Request, res: Response) {
       updated_at: new Date(),
     },
   });
-  sendSuccess(res, 200, "Permission updated", updated);
+  sendFastSuccess(res, 200, permissionSerializer, {
+    status: "success",
+    message: "Permission updated",
+    data: { ...updated, id: updated.id.toString() },
+  });
 }
 
 export async function deletePermission(req: Request, res: Response) {

package/src/core/redis.ts

@@ -31,7 +31,7 @@ redis.on("ready", () => {
   // console.log("Redis connected!");
 });
 
-redis.on("error", (err) => {
+redis.on("error", (_err) => {
   // If connection fails and we haven't switched to mock yet
   if (!isRedisConnected && !(redis instanceof RedisMock)) {
     // console.log("Redis connection failed, switching to in-memory mock...");
@@ -98,9 +98,10 @@ export async function initRedis() {
 
 // Proxy handler to forward all calls to activeRedis
 const redisProxy = new Proxy({} as Redis, {
-  get: (target, prop) => {
-    // @ts-ignore
-    return activeRedis[prop];
+  get: (_target, prop) => {
+    // If accessing a property on the proxy, forward it to activeRedis
+    const value = (activeRedis as any)[prop];
+    return value;
   },
 });
 

package/src/core/serializer.ts

@@ -0,0 +1,63 @@
+import fastJson from "fast-json-stringify";
+
+// Cache untuk menyimpan fungsi stringify yang sudah dicompile
+// Key: Nama schema/Identifier, Value: Fungsi stringify
+const serializerCache = new Map<string, (doc: any) => string>();
+
+/**
+ * Membuat atau mengambil serializer yang sudah dicompile.
+ *
+ * @param key Identifier unik untuk schema (misal: 'UserResponse', 'ProductList')
+ * @param schema JSON Schema definition (Standard JSON Schema)
+ * @returns Fungsi yang mengubah object menjadi JSON string dengan sangat cepat
+ */
+export function getSerializer(key: string, schema: any) {
+  if (serializerCache.has(key)) {
+    return serializerCache.get(key)!;
+  }
+
+  const stringify = fastJson(schema);
+  serializerCache.set(key, stringify);
+  return stringify;
+}
+
+/**
+ * Helper untuk mendefinisikan schema standar response Lapeh
+ * { status: "success", message: string, data: T }
+ */
+export function createResponseSchema(dataSchema: any) {
+  return {
+    title: "StandardResponse",
+    type: "object",
+    properties: {
+      status: { type: "string" },
+      message: { type: "string" },
+      data: dataSchema,
+    },
+  };
+}
+
+/**
+ * Helper khusus untuk response paginasi
+ * { status: "success", message: string, data: { data: T[], meta: ... } }
+ */
+export function createPaginatedResponseSchema(itemSchema: any) {
+  return createResponseSchema({
+    type: "object",
+    properties: {
+      data: {
+        type: "array",
+        items: itemSchema,
+      },
+      meta: {
+        type: "object",
+        properties: {
+          page: { type: "integer" },
+          perPage: { type: "integer" },
+          total: { type: "integer" },
+          lastPage: { type: "integer" },
+        },
+      },
+    },
+  });
+}

package/src/middleware/auth.ts

@@ -1,6 +1,5 @@
 import { Request, Response, NextFunction } from "express";
 import jwt from "jsonwebtoken";
-import { prisma } from "../core/database";
 import { sendError } from "../utils/response";
 import { ACCESS_TOKEN_EXPIRES_IN_SECONDS } from "../controllers/authController";
 

package/src/middleware/rateLimit.ts

@@ -1,5 +1,5 @@
 import rateLimit from "express-rate-limit";
-import { redis } from "../core/redis"; // Optional: Use Redis for distributed rate limiting
+// import { redis } from "../core/redis"; // Optional: Use Redis for distributed rate limiting
 
 // Rate limiting untuk mencegah brute force dan DDoS ringan
 export const apiLimiter = rateLimit({