Opticore Router

A lightweight TypeScript/Express router utility for building modular, context-aware routes with optional Passport authentication as middleware. Router allow to create a route for by two ways

Table of Contents

1. Introduction
2. Installation
3. Usage
   • Standalone Routes
   • Controller Collection Routes
   • Wrapper Handler
4. API Reference
   • OpticoreStandaloneRouter
   • OpticoreRouterCollectionRouter
   • wrapHandler
5. Error Handling
6. License

Introduction

opticore-router provides a structured way to define Express routes in TypeScript using a single context object instead of the usual req, res, next signature.

It supports:

• Modular standalone routes
• Grouped controller routes
• Optional Passport authentication
• Automatic JSON response handling
• Async/await-friendly wrapper for handlers

Installation

npm install opticore-router
# Opticore Router Usage Examples

import express from "opticore-express";
import { OpticoreStandaloneRouter, OpticoreRouterCollectionRouter, wrapHandler } from "opticore-router";

Usage

Standalone Routes

const app = express();


const router = new OpticoreStandaloneRouter();

router.addRoute({
  path: "/your-route",
  method: "get",
  handler: async ({ req }) => ({ msg: "pong" })
});

app.use(router.getRoute());

Controller Collection Routes

const userRouter = new OpticoreRouterCollectionRouter("/users");

userRouter.addRoutes([
  {
    path: "/",
    method: "get",
    handler: async ({ req }) => ({ list: ["Alice", "Bob"] })
  },
  {
    path: "/:id",
    method: "delete",
    handler: async ({ req }) => ({ deleted: req.params.id }),
    middlewares: [] // optional middleware array
  }
]);

app.use(userRouter.getRoute("jwt"));

single router using

method : you can define your method here as post or put or get or delete.

path : set the path here

handler : At this line, handler is a function which receive the controller method

middleware : you can set true if you want to use any auth middleware, so you should define a strategy name and set the Options as an object same likely IAuthPassportOptions if you want it.

 OpticoreRouterModule.route("delete", "/ads", () => {}, true, "jwt", {session: true});

multiple routers using

method : you can define your method here as post or put or get or delete.

myController : represent the controller that you want to use

routers : is an array which must contains a route object like this { path: "/ads", handler: () => {} }

middleware : can get auth middleware or null as value

  OpticoreRouterModule.routes(
      myController, 
      [ 
          { 
              path: "/ads" ,
              handler: context => {} 
          }
      ], 
      null
  );

Wrapper Handler

wrapHandler converts your TRouteHandler into an Express RequestHandler automatically:

const handler = async ({ req, res }) => ({ hello: req.query.name || "world" });
app.get("/hello", wrapHandler(handler));

Features

• Automatically sends res.json if handler returns a value
• Supports async/await
• Allows manual res.send() if needed

Route Flow Diagram

API Reference

OpticoreStandaloneRouter

| Method | Description | |--------|-------------| | addRoute(route: ISingleRouterConfig) | Adds a standalone route to the router. | | getRoute(strategy?: string, options?: IAuthPassportOptions): Router | Returns a fully configured Express Router, optionally protected by Passport strategy. |

OpticoreRouterCollectionRouter

| Method | Description | |--------|-------------| | addRoutes(routes: IMultipleRouterConfig<TContext>[]) | Adds multiple routes to this router collection. | | getRoute(strategy?: string, options?: IAuthPassportOptions): Router | Returns an Express Router mounted under basePath. Routes with middleware: true will use Passport authentication if strategy provided. |

wrapHandler

wrapHandler(handler: TRouteHandler): RequestHandler

Error Handling

• All handlers are wrapped with try/catch
• Exceptions are passed to Express error middleware via next(err)
• Routes automatically send 204 No Content if handler returns undefined

All handlers are wrapped with try/catch

Exceptions are passed to Express error middleware via next(err)

Routes automatically send 204 No Content if handler returns undefined

Security Issues

https://github.com/guyzoum77/opticore-router/issues

Contributing

OptiCore Router Module is an Open Source, so if you would like to contribute, you're welcome. Clone repository and open pull request.

About

OptiCore Router Moduleis led by Guy-serge Kouacou and supported by Guy-serge Kouacou