Introduction

A Lean Framework for Enterprise Scalability.

GamanJS is a lightweight, fast HTTP framework built on top of Bun runtime. Designed for building structured REST APIs with a clean Controller-Service-Middleware architecture that’s easy to maintain.

✨ Key Features

• ⚡ Blazing Fast — Built on Bun’s native Bun.serve() for maximum performance
• 🏗️ Structured Architecture — Built-in Controller / Service / Middleware pattern
• 📦 Fluent Response API — Clean and consistent response handling via ctx.send()
• 🔀 Declarative Router — Clean route definition with composeRouter
• 🧩 Type-Safe DI — Simple dependency injection via destructuring and TypeScript
• 🛡️ Exception Handling — Global & per-route exception handlers
• 🎯 Middleware Priority — Control middleware execution order

📚 Table of Contents

Page	Description
Getting Started	Installation & creating a new project
Bootstrap	defineBootstrap & server configuration
Router	Route definition, grouping, & methods
Controller	Creating controllers with composeController
Service	Business logic with composeService
Middleware	Middleware & priority system
Response	Fluent response handling with ctx.send
Context	Request context (ctx) in detail
Exception Handler	Global & per-route error handling

🚀 Quick Start

bun create gaman@latest

Default Project Structure

GamanJS embraces the Feature-Based Modularity philosophy. For better scalability, we recommend placing your routes, controllers, and services within feature modules:

src/
├── index.ts                 # The Orchestrator (Entry Point)
└── modules/
    └── app/                 # Main Application Module
        ├── controllers/
        │   └── AppController.ts
        ├── services/
        │   └── AppService.ts
        ├── middlewares/
        │   └── AppMiddleware.ts
        └── AppRoutes.ts     # Routes for this module

Enterprise Project Architecture

For large-scale production applications, you can add more feature modules:

src/
├── index.ts                 # The Orchestrator (Entry Point)
├── database/                # Database Configuration
└── modules/                 # Powerhouse of your Application
    ├── app/                 # Infrastructure Module (Global/Shared)
    │   ├── controllers/     # Handlers for Global Requests (Health, Index)
    │   │   └── AppController.ts
    │   ├── services/        # Shared Utilities & System Services
    │   │   └── AppService.ts
    │   └── AppRoutes.ts     # Global Middleware & Base Routing
    │
    └── user/                # Feature Module (Example: User Management)
        ├── controllers/     # Request Handlers (Login, Register, Profile)
        │   └── UserController.ts
        ├── services/        # Business Logic (Auth Logic, User CRUD)
        │   └── UserService.ts
        ├── models/          # Data Access Layer (Powered by @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 services
  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();
});

📄 License

MIT © Angga7Togk