@refkinscallv/express-routing-ts v1.2.1

📦 @refkinscallv/express-routing-ts

Laravel-style routing system for Express.js in TypeScript. Simplify your route definitions, middleware stacks, and controller bindings like a boss.

🛠 Installation

npm install @refkinscallv/express-routing-ts

🧪 See Example

Curious how it all comes together?
👉 Check out example/index.ts for a full working demo!

📚 Features

• ✅ Simple route declarations (get, post, etc.)
• ✅ Grouped routes with prefix
• ✅ Middleware stack: global, group, and per-route
• ✅ Controller-method pair as route handler
• ✅ Consistent handler format using HttpContext
• ✅ Auto-instantiate controllers
• ✅ Express-compatible

🧩 Type Definitions

type RouteMiddleware = (req: Request, res: Response, next: NextFunction) => void;

type RouteMethod = 'get' | 'post' | 'put' | 'patch' | 'delete' | 'options' | 'head';

type HttpContext = {
  req: Request;
  res: Response;
  next: NextFunction;
};

type RouteHandler = ((ctx: HttpContext) => any) | [any, string];

interface RouteDefinition {
  methods: RouteMethod[];
  path: string;
  handler: RouteHandler;
  middlewares?: RouteMiddleware[];
}

✨ Usage

🔹 1. Basic Route

Routes.get('/hello', ({ res }) => {
  res.send('Hello World');
});

🔹 2. With Middleware

Routes.post(
  '/submit',
  ({ res }) => res.send('Submitted'),
  [authMiddleware],
);

🔹 3. Controller Binding

You can use [ControllerClass, 'methodName']:

class UserController {
  index({ res }: HttpContext) {
    res.send('User list');
  }
}

Routes.get('/users', [UserController, 'index']);

⚠️ Controller will be instantiated if not passed as an object.

🔹 4. Grouped Routes

Use Routes.group() to prefix and stack middleware:

Routes.group('/admin', () => {
  Routes.get('/dashboard', ({ res }) => res.send('Admin Dashboard'));
}, [adminOnly]);

🔹 5. Global Middleware Scope

Wrap multiple routes in a shared global middleware:

Routes.middleware([authMiddleware], () => {
  Routes.get('/me', ({ res }) => res.send('My Profile'));
});

🔹 6. Register to Express

import express from 'express';
import Routes from '@refkinscallv/express-routing-ts';

// registered your routes
// import 'path/to/routes.ts'

const app = express();
const router = express.Router();

Routes.apply(router);

app.use(router);
app.listen(3000);

📖 API Reference

📌 Routes Methods

📌 Static Methods

📌 Execution Flow

Middleware Execution Order:

[ Global Middleware ] → [ Group Middleware ] → [ Route Middleware ]

Handler Execution:

• If a function → Executed directly

• If [Controller, 'method']:

  • Instantiates controller (if class passed)
  • Binds and executes method

🧪 Example

class HomeController {
  index({ res }: HttpContext) {
    res.send('Welcome to Home!');
  }
}

Routes.group('/v1', () => {
  Routes.get('/', [HomeController, 'index']);
});

🧠 Tips

• Route paths will be automatically cleaned to avoid duplicate slashes (// → /).
• Controller methods are bound to their instance or static context.
• Handler functions can be async or return a Promise.

🤝 License

MIT License © 2025 [Refkinscallv]