expressjs-route-mapper

expressjs-route-mapper

HTTP dynamic routing with Express.js

About

The motivation for this module is to provide a high-level abstraction of routes in express.js. It is written in JavaScript, and is 100% MIT licensed.

• a simple, easy method for generating restful routes for a model.
• easy declaration of your "root" or "home" route.
• support virtualhost, domain specific routes
• support condition inheritance
• optional definition of a "before wrapper" function, which is called before request handling is made.
• optional support middleware

Install

npm install expressjs-route-mapper --save

Supported HTTP methods:

  Method    Scope         Semantics
  GET       collection    Retrieve all resources in a collection
  GET       resource      Retrieve a single resource
  HEAD      collection    Retrieve all resources in a collection (header only)
  HEAD      resource      Retrieve a single resource (header only)
  POST      collection    Create a new resource in a collection
  PUT       resource      Update a resource
  PATCH     resource      Update a resource
  DELETE    resource      Delete a resource
  COPY      resource      Clone/Copy of an existing resource.
  PURGE     resource      pick out an object from the cache and discard
  TRACE     resource      TRACE allows the client to see testing or diagnostic information.
  OPTIONS   any Return available HTTP methods and other options

Examples

Here is an example on how to use it:

Basic route

  express = require("express");
  app = express();
  require('expressjs-route-mapper').use(app);

  app.routeMapper({
    base: '/users/:user_id/tables/:table_id',
    routes: {
      '/stories': {
        'get': function(req, res){ res.send('hello get'); },
        'delete': function(req, res){ res.send('hello delete'); },
        'put': function(req, res){ res.send('hello put'); },
        'post': function(req, res){ res.send('hello post'); },
      }
    }
  });

These are the routes that will get created with the code above:

Method    URL
GET       /users/:user_id/tables/:table_id/stories
POST      /users/:user_id/tables/:table_id/stories
DELETE    /users/:user_id/tables/:table_id/stories
PUT       /users/:user_id/tables/:table_id/stories

Basic route with before wrapper

Here we have route [IndexRoute] with before callback [IndexRoute.before] which run before the main route IndexRoute. This is useful for security check or validate a user before render the main route

• note: before condition inherits down to child routes

  express = require("express");
  app = express();
  require('expressjs-route-mapper').use(app);

  IndexRoute = function(req, res){
    return 'Hello World'
  }

  IndexRoute.before  = function(req, res){
    return 'Hello World'
  }

  app.routeMapper({
    base: '/home',
    routes:
      'get': function(req, res, next){
        res.send('Hello World');
      }
  });

Basic route with base root

Declare your root or home url with the base options:

  app.routeMapper({
    base: '/product',
    routes: {
      'get': function(req, res, next){
        res.send('Hello World');
      },
      '/category':{
        'get': function(req, res, next){
          res.send('Hello World');
        }
      }
    }
  });

These are the routes that will get created with that method call:

Method  URL
GET     /product
GET     /product/category

Route mapping with multiple layers

  express = require("express");
  app = express();
  require('expressjs-route-mapper').use(app);

  app.routeMapper({
    routes: {
      '/product': {
        'get': function(req, res){
          return "Hello World, I'm an http get method"
        },
        'post': function(req, res){
          return "Hello World, I'm an http post method"
        },
        '/byId':{
          'get': function(req, res){
            return "my product id is 10"
          },
          'delete': function(req, res){
            return "Hello World, I'm an http delete method"
          },
        }
      }
    }
  });

These are the routes that will get created with that method call:

Method    URL
GET       /product
POST      /product
GET       /product/byId
Delete    /product/byId

Virtual Host

domain specific routes

  express = require("express");
  app = express();
  require('expressjs-route-mapper').use(app);
  myDomainServer = express();
  myDomainServer.get('/', function(req, res){
    res.send('hello one.lvh.me');
  })

  app.routeMapper({
    host: 'one.lvh.me',
    server: myDomainServer, //optional server
    base: '/my-route',
    routes: {
      'get': function(req, res){ res.send('hello one.lvh.me/my-route'); },
    }
  });

  app.routeMapper({
    host: 'two.lvh.me',
    base: '/your-route',
    routes: {
      'get': function(req, res){ res.send('hello two.lvh.me/your-route'); },
    }
  });

These are the routes that will get created with that method call:

Method    URL          Domain
GET       /my-route    http://one.lvh.me/my
GET       /your-route  http://your-domain/your-domain

Supported domain patterns:

  lvh.me        //domain www
  www.lvh.me    //sub-domain www
  *.lvh.me      //any sub-domain

Todo

• ways to customize, override and extend the generated restful routes

Notes

Inspired by express.js examples

License

MIT © Carlos Marte