Introduction

A Lean Framework for Enterprise Scalability.

GamanJS adalah framework HTTP ringan dan cepat yang dibangun di atas Bun runtime. Dirancang untuk membangun REST API yang terstruktur dengan arsitektur Controller-Service-Middleware yang bersih dan mudah di-maintain.

✨ Fitur Utama

• ⚡ Blazing Fast — Dibangun di atas Bun Bun.serve() untuk performa maksimal
• 🏗️ Arsitektur Terstruktur — Pola Controller / Service / Middleware bawaan
• 📦 API Response Fluent — Penanganan response yang bersih dan konsisten via ctx.send()
• 🔀 Router Deklaratif — Definisi route yang bersih dengan composeRouter
• 🧩 Type-Safe DI — Dependency injection sederhana via destrukturisasi dan TypeScript
• 🛡️ Exception Handling — Global & per-route exception handler
• 🎯 Middleware Priority — Kontrol urutan middleware eksekusi

📚 Daftar Isi

Halaman	Deskripsi
Memulai	Instalasi & membuat project baru
Bootstrap	defineBootstrap & konfigurasi server
Router	Definisi route, grouping, & method
Controller	Membuat controller dengan composeController
Service	Business logic dengan composeService
Middleware	Middleware & priority system
Response	Penanganan response fluent dengan ctx.send
Context	Request context (ctx) secara detail
Exception Handler	Error handling global & per-route

🚀 Quick Start

bun create gaman@latest

Struktur Project Default

GamanJS mengadopsi filosofi Feature-Based Modularity. Untuk skalabilitas yang lebih baik, kami merekomendasikan penempatan route, controller, dan service di dalam modul fitur:

src/
├── index.ts                 # The Orchestrator (Entry Point)
└── modules/
    └── app/                 # Modul Utama Aplikasi
        ├── controllers/
        │   └── AppController.ts
        ├── services/
        │   └── AppService.ts
        ├── middlewares/
        │   └── AppMiddleware.ts
        └── AppRoutes.ts     # Route untuk modul ini

Enterprise Project Architecture

Untuk aplikasi skala produksi yang besar, kamu bisa menambahkan lebih banyak modul fitur:

src/
├── index.ts                 # The Orchestrator (Entry Point)
├── database/                # Konfigurasi Database
└── modules/                 # Pusat Logika Aplikasi
    ├── app/                 # Modul Infrastruktur (Global/Shared)
    │   ├── controllers/     # Handler untuk Request Global (Health, Index)
    │   │   └── AppController.ts
    │   ├── services/        # Utility Shared & System Services
    │   │   └── AppService.ts
    │   └── AppRoutes.ts     # Middleware Global & Base Routing
    │
    └── user/                # Modul Fitur (Contoh: User Management)
        ├── controllers/     # Request Handlers (Login, Register, Profile)
        │   └── UserController.ts
        ├── services/        # Business Logic (Auth Logic, User CRUD)
        │   └── UserService.ts
        ├── models/          # Data Access Layer (Didukung @gaman/orm)
        │   └── UserModel.ts
        └── UserRoutes.ts    # Scoped Routes & Feature Middleware

src/index.ts

import { defineBootstrap } from 'gaman';
import AppRoutes from './modules/app/AppRoutes';

defineBootstrap(async (app) => {
  app.mount(AppRoutes);
  app.mountServer({ http: 3431 });
});

src/modules/app/AppRoutes.ts

import { composeRouter } from 'gaman/compose';
import { AppService } from './services/AppService';
import AppController from './controllers/AppController';

export default composeRouter((r) => {
  // Inject service
  r.mountService({
    appService: AppService(),
  });

  r.get('/', [AppController, 'HelloWorld']);
});

src/modules/app/controllers/AppController.ts

import { composeController } from 'gaman/compose';
import { AppService } from '../services/AppService';

export type Deps = {
  appService: AppService;
};

export default composeController(({ appService }: Deps) => ({
  HelloWorld(ctx) {
    return ctx.send(appService.WelcomeMessage()).ok();
  },
}));

src/modules/app/services/AppService.ts

import { composeService } from 'gaman/compose';
import type { RT } from 'gaman/types';

export const AppService = composeService(() => ({
  WelcomeMessage() {
    return '❤️ Welcome to GamanJS';
  },
}));

export type AppService = RT<typeof AppService>;

src/modules/app/middlewares/AppMiddleware.ts

import { composeMiddleware } from 'gaman/compose';

export default composeMiddleware(async (ctx, next) => {
  console.log(`[${ctx.request.method}] ${ctx.path}`);
  return next();
});

📄 Lisensi

MIT © Angga7Togk