Mahmud Bhai Er Server 🚀

The Fast, Flexible, and Type-Safe Framework for Modern Web Development.

🌟 Introduction

Mahmud Bhai Er Server is a lightweight web framework built on standard Web APIs (Request, Response). It is designed to be:

• Fast: Minimal overhead, using a Radix Tree router.
• Simple: Easy to learn API, similar to Express or Hono.
• Flexible: Runs on Node.js, Bun, Deno, or Cloudflare Workers.
• Type-Safe: Built with TypeScript in mind.

📦 Installation

npm install mahmud-bhai-er-server

🚀 Quick Start

Create a file named index.ts:

import { MahmudServer } from 'mahmud-bhai-er-server';

const app = new MahmudServer();

app.get('/', (c) => c.text('Hello World!'));

app.listen(3000);

Run it:

npx tsx index.ts

📚 Documentation

1. Routing & Path Parameters 🛣️

We support standard HTTP methods: get, post, put, delete, patch.

New Feature: Auto-completion for Path Parameters!

app.get('/users/:id', (c) => {
  // TypeScript knows 'id' exists!
  const id = c.param('id');
  return c.json({ userId: id });
});

app.get('/posts/:postId/comments/:commentId', (c) => {
  // TypeScript suggests 'postId' and 'commentId'
  const postId = c.param('postId');
  const commentId = c.param('commentId');
  return c.text(`Post: ${postId}, Comment: ${commentId}`);
});

2. Context (c)

The Context object is passed to every handler. It wraps the standard Request and provides helpers.

• c.req: The raw Request object.
• c.body(): Parse JSON body.
• c.text(string): Return a text response.
• c.json(object): Return a JSON response.
• c.param(key): Get a path parameter (Type-Safe!).
• c.set(key, value): Set a variable.
• c.get(key): Get a variable.

3. Middleware

Middleware allows you to intercept requests. We use the "Onion Model" (like Koa).

// Global Middleware
app.use(async (c, next) => {
  console.log(`Incoming: ${c.req.method} ${c.req.url}`);
  await next(); // Call the next handler
  console.log('Response sent!');
});

Built-in Middleware

We provide some common middleware out of the box:

import { logger, bearerAuth } from 'mahmud-bhai-er-server';

app.use(logger());
app.use(bearerAuth('my-secret-token'));

4. Type Safety 🛡️

You can define your own environment variables (like User, RequestID) and get full type safety and auto-completion!

import { MahmudServer } from 'mahmud-bhai-er-server';

// 1. Define your types
type Env = {
  user: {
    id: string;
    name: string;
  };
  requestId: string;
};

// 2. Pass it to the server
const app = new MahmudServer<Env>();

app.use(async (c, next) => {
  // TypeScript knows 'requestId' is a string!
  c.set('requestId', '123');
  await next();
});

app.get('/', (c) => {
  // TypeScript knows 'user' is { id: string, name: string }
  // You get auto-completion here!
  const user = c.get('user');
  return c.json({ user });
});

5. Interoperability (Using Hono, etc.)

"What if I need a feature that isn't available?"

Because MahmudServer uses standard Web APIs, you can mount any other framework (like Hono, Itty Router, etc.) inside it!

We even re-export Hono for you as MahmudHono!

import { MahmudServer, MahmudHono } from 'mahmud-bhai-er-server';

const app = new MahmudServer();
const hono = new MahmudHono();

hono.get('/cool', (c) => c.text('Hono is handling this!'));

// Mount Hono at /hono
app.router.add('ALL', '/hono/:path', (c) => {
  // Rewrite URL to strip prefix if needed
  const url = new URL(c.req.url);
  const newUrl = new URL(url.pathname.replace('/hono', ''), url.origin);
  const newReq = new Request(newUrl.toString(), c.req);

  return hono.fetch(newReq);
});

app.listen(3000);

This gives you the best of both worlds: Simplicity by default, power when you need it.

🤝 Contributing

We welcome contributions! Please open an issue or submit a PR.

📄 License

MIT