Skip to content

node-muneem/anumargak

Repository files navigation

अनुमार्गक (anumargak)

Fastest HTTP Router

Known Vulnerabilities Travis ci Build Status Coverage Status NPM total downloads

Become a Patron! Paypal donate button

Features

  • Fastest node js router (as far as Google & I know)
  • Framework independent.
  • Supports static and dynamic both type of URLs.
  • Supports path parameter with defined type \this\is\:num([0-9]+)
  • Support multiple path parameters.
  • Handles enumerated URLs \login\as\:role(admin|staff|user)
  • Supports wildchar \this\is\*, \this\is\wild*
  • You need not to register 2 separate routes for trailing slash. \like\me\ and \like\me.
  • You may skip leading slash while registering the route, though not recommended. \like\me and like\me.
  • Capture parameters' value for dynamic URLs.
  • Add similar but not same URLs : \this\is\:age([0-9]+) and \this\is\:name([a-zA-Z]+)
  • Support shorthand methods
  • You can always have a count on registered routes.
  • Supports versioned routes.
  • You can name regular expressions to increase code redability.
  • Support events

Usage

const http = require('http')
const router = require('anumargak')({
  defaultRoute : defaultHandler,//it'll be called when no route matches. If it is not set the we'll set statusCode to 404
  ignoreTrailingSlash: true,
  ignoreLeadingSlash: true,
  allowUnsafeRegex: false
})

router.on('GET', '/', (req, res, params) => {
  //process the request response here
})

const server = http.createServer((req, res) => {
  router.lookup(req, res)
})

server.listen(3000);

on(method, url [, options] , handler [, store] )

To register a route.

router.on("GET", "/this/is/static", handler);
router.on(["POST","PUT"], "/this/is/static", handler);

Dynamic URL

You can register dynamic url with multiple path paramters

router.on("GET", "/this/is/:dynamic", handler);
router.on("GET", "/this/is/:dynamic", handler);//it will error
router.on("GET", "/this/is/:dynamic/with/:pattern(\\d+)", handler);
//Eg: params = { dynamic : val, pattern: 123}
router.on("GET", "/this/is/:dynamic/with/:two:params", handler);// multiple parameters
router.on("GET", "/this/is/:dynamic/with/:two(\\d+):params", handler);//multiple parameters with pattern
router.on("GET", "/this/is/:dynamic/with/:two(\\d+)rest", handler);//single parameter

Enumerated URL

Anumargak handls enumerated URLs in static way. Because static URLs can be looked up faster than dynamic URLs.

router.on("GET", "/login/as/:role(admin|user|staff)", handler);

wildcard

wild cards are helpful when a route handler wants to control all the underlying paths. Eg. a handler registered with /help* may take care of all the help pages and static resources under the same path. You can check आलेख (Aalekh) for live example.

//this/is/juglee/and/
//this/is/juglee/and/wild
//this/is/juglee/and/wild/and/unknown
router.on("GET", "/this/is/:dynamic/and/*", handler);

//this/is/juglee/and/wild
//this/is/juglee/and/wildlife
//this/is/juglee/and/wild/and/unknown
router.on("GET", "/this/is/:dynamic/and/wild*", handler);

shorthand methods

var router = Anumargak();

router.get("/this/is/:dynamic", () => 30);
router.head("/this/is/:dynamic", () => 30);
router.post("/this/is/:dynamic", () => 30);
router.put("/this/is/:dynamic", () => 30);
router.delete("/this/is/:dynamic", () => 30);

off(method, url [, version] )

To remove a registered route. If no route is found no error will be thrown.

anumargak.off("GET", "/this/is/static");
anumargak.off("GET", "/this/is/:dynamic");
anumargak.off("GET", "/this/is/*/really/wild");
anumargak.off("GET", "/login/as/:role(admin|user|staff)"); //it'll delete all the versions

Enumerated URLs

an enumerated URL can be deleted multi steps

anumargak.off("GET", "/login/as/:role(admin|user|staff)");
//or
anumargak.off("GET", "/login/as/admin");
anumargak.off("GET", "/login/as/user");
anumargak.off("GET", "/login/as/staff");
//or
anumargak.off("GET", "/login/as/:role(user|staff)");
anumargak.off("GET", "/login/as/admin");

Versioned URLs

version can be provided as an additional parmeter. Valid values are:

  • 1.2.3 : It'll delete only one URL
  • 1.2.x : It'll delete all the URLs with different patche versions : 1.2.0, 1.2.1 ...
  • 1.x : It'll delete all the URLs with different minor versions : 1.2.0, 1.2.1, 1.3.5 ...
anumargak.off("GET", "/this/is/static", version);

Please note that, if you delete a route without specifying versions then all the versioned routes will also be deleted.

find(method, url [, version])

To find a registered route. It returns;

{
  handler : function(){}, //registered function
  params : {}, //path parameters
  store : any // extra data provided at the time of registering the route
}

quickFind(method, url [, version])

To find a registered route. It returns;

{
  handler : function(){}, //registered function
  store : any // extra data provided at the time of registering the route
}
  • alternate signature quickFind(request)
  • quickFind() is faster than find() as it doesn't process path parameters.

lookup(request, response, store)

This method reads request object to fetch url, method, and accept-version header to find matching route and then run the handler.

The handler should accept: request, response, and store. request._path.params is an object of path parameters.

Lookup method also save _path, _queryStr, and _hashStr in request object to save re-effort of spliting them. _path is an object with two properties: url, params.

lookupWithEvents(request, response, store)

save as above but raises events

count

You can always check how many routes are registered. If you delete some routes count will be decreased.

Other detail

Similar but not same URLs

You can register the URLs which look similar but not exactly same.

const anumargak = require('anumargak')()
//this/is/my/75
anumargak.on("GET", "/this/is/my/:age([0-9]{2,3})", handler);

//this/is/my/amit
anumargak.on("GET", "/this/is/my/:name([a-zA-z]+)", handler);

anumargak.on("GET", "/login/as/:role(admin|user|staff)", handler);
anumargak.on("GET", "/login/as/:role(developer|tester|hacker)", handler);

Named Expressions

Anumargak lets you add named expressions. You can use them at the time of registering the route.

router.addNamedExpression("num","\\d+");
router.addNamedExpression({
   "name1" : "regx1",
   "name2" : "regx2",
});

Example routes

/send/to/:phone(:phone:)
/authenticate/:token(:alphanum:)

Adding them make this router simple to use.

accept-version

Same routes can be registerd with different versions. Lookup method reads accept-version header to read the version or you can pass the version in find method directly.

router.on('GET', '/some/route', { version: '1.2.0' }, (req, res, params) => {
  //..
})

router.get( '/some/route', { version: '1.2.3' }, (req, res, params) => {
  //..
})

router.find('GET', '/some/route', "1.2.3");
router.lookup(req, res);

Note that

  • A route can be registered with and without version. In this case, if the accept-version header presents then versioned route handler will be returned.
  • Value of accept-version header can be : "1.2.0", "1.2.x", "1.x", "*"

Events

You can register events.

router.on(eventName, fn);

Following events are supported;

  • request - When lookup method is called.
  • found - Before calling registered handler. (alias: route )
  • not found - When there is no registered handler. (alias: default )

These events will be called when you use lookupWithEvents().

Mappings

Anumargak supports

  • one-to-one mapping: One url to one handler
router.on( "single/url", fn );
  • one-to-many mapping: One url to series of handlers
router.on( "single/url", [fn, fn] );
  • many-to-one mapping: Multiple urls to one handler
router.on( ["single/url", "other/url" ], fn );
  • many-to-one mapping: Multiple urls to series of handlers
router.on( ["single/url", "other/url" ], [fn, fn] );

Benchmark

Method URL type अनुमार्गक (Anumargak) v1.7.0 Find My Way v1.15.1
Find static 24369856.07 2614866.631
Find dynamic 2405576.122 1106656.051
Find dynamic + query param 1665114.806 1082533.894
Find Enum 23151436.16 1298019.289
Find wildchar 2591342.638 1630995.248
Find versioned static 1958139.854 263611.4248
Find versioned Dynamic 465584.9696 315857.0792
Look static 23614465.42 2201314.59
Look dynamic 2032592.029 940862.1238
Look dynamic + query param 1403264.652 923533.114
Look Enum 12662923.03 1066446.935
Look wildchar 2251611.449 1335382.238
Look versioned static 1313886.055 0
Look versioned Dynamic 392754.437 252312.1124

Note : Above benchmark has been taken on 16gb RAM ubuntu 17.10 machine with node v9.5.0 and npm v5.6.0

chart

Integration with other web frameworks

Muneem framework is already based on Anumargak. To use it with express js;

const app = require("express")();
const Anumargak = require("anumargak");
const router = new Anumargak();

app.use((req,res) => router.lookup(req, res));

router.on("GET", "/", (req, res) => {
    //..
});

app.listen(3002);

Use it with restana

const anumargak = require('anumargak')
const service = require('restana')({
  routerFactory: (options) => {
    return anumargak(options)
  }
})

service.get("/this/is/static", function(req, res){
    res.send("Hello");
})

service.get("/this/is/:dynamic", function(req, res){
    res.send("Hello");
})


service.start(3001).then((server) => {
    console.log("server has been started on port 3001")
});

Worth to mention

  • BigBit standard : A standard to reprent any number in the universe in comparitively less space and without precision loss. A standard to save space to represent any text string in comparision of UTF encoding.
  • imglab : Speedup and simplify image labeling / annotation process online. Supports multiple formats, one click annotation, easy interface and much more.
  • stubmatic : A stub server to mock behaviour of HTTP(s) / REST / SOAP services. You can also mock binary formats.
  • मुनीम (Muneem) : A webframework made for all team members.
  • शब्दावली (shabdawali) : Amazing human like typing effects beyond your imagination. Check वार्ता for talking/chatting effect.

Contributors

Disclaimer

I initially used find-my-way npm package for मुनीम (Muneem) framework. But then I realized that lookup for static URLs is comparitively slower. Hence I develop this library. If you notice, I tried to keep the naming convention and syntaxes common wherever possible to reduce the time to switch from one library to another and to keep learning curve smaller.

About

Simple but Fastest Web Router in nodejs

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Contributors 4

  •  
  •  
  •  
  •