json-routing

KO | EN

gitlite — search

#javascript #hacktoberfest #react #ai #typescript #llm #go #golang #linux #awesome #awesome-list #vue #pytorch #mcp

(★ 9)

Node json configuration routing

json-routing Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

JSON Routes
===================

[![Build Status](https://travis-ci.org/gimox/json-routing.svg?branch=2.0)](https://travis-ci.org/gimox/json-routing)
[![npm version](https://badge.fury.io/js/json-routing.svg)](https://badge.fury.io/js/json-routing)
[![Coverage Status](https://coveralls.io/repos/github/gimox/json-routing/badge.svg?branch=2.0)](https://coveralls.io/github/gimox/json-routing?branch=2.0)

Look at branch [v1.x](https://github.com/gimox/json-routing/tree/1.x) for older release.

- Typescript code, more optimized
- more speed
- remove some unused option
- make code more extensible and simple
- add automatic JWT route protection with auth0/express-jwt
- add route validator with express-validator
- prepare it for something more......

MAKE ME THE CODE
-------------

#### 1 init module

**Typescript**

```javascript
import {JsonRoute} from "json-routing";

const routeInfo:Array<any> = new JsonRoute(app, {
    "routesPath": "./api/routes",
    "processdir": __dirname
}).start();

```

**JS ES6**

```javascript
let Routing = require("json-routing")

let routeInfo = new Routing.JsonRoute(app, {
    "routesPath": "./api/routes",
    "processdir": __dirname
}).start();
```

#### 2 create routes

**Create a route file definition**

```json
{
"/admin": {
    "GET": {
      "route": "action",
      "policy": [
        "test:check",
        "test:all",
        "./subfolder/test2:index"
      ]
    },
    "POST": {
      "route": "action",
      "policy": [
        "test:all",
      ]
    }
 },
  "/dashboard": {
    "GET": {
      "route": "dashboard",
      }
  }

}
```

Routig with pure regular expression, add prefix "RE " before uri:

```json
{
  "RE /.*fly$/": {
    "GET": {
      "route": "index"
    }
  }
}
```

WHAT IS IT?
-------------
Make routes much easier to use in MVC format.
I've been searching for a while for a nodejs routing solution with a:

-  simple configuration,
 -  super performance,
 -  simple code,
 -  MVC organization,
 -  manage only routing, no other auto magic api creation
 -  customizable
 -  least possible dependency

This is: json-routes.

How It Works
-------------

**The basic concepts.**
Create a json file with your routing config and add code logic in a external file called *controller* , creating an MVC style structure.

I followed the Expressjs 4 routing standards, helping the developer to manage the routes creation and project organization faster and in the standard synthax. Look at [express routing guide](http://expressjs.com/en/guide/routing.html)
 for a complet route pattern syntax

Proposed Structure
-------------
This is an example of the default proposed structure, you can customize and change as you prefer.

```
project root
├── controllers/
│   ├── IndexController.js
│   ├── AuthController.js
│   ├── UsersController.js
├── policy/
│   │   ├── AuthorizationPolicy.js
│   │   ├── mymiddleware.js
├── routes/
│   │   │   ├── auth.json
│   │   │   ├── users.json
│   │   │   ├── index.json
├── app.js/
├── package.json/
├── README.md/
```
- **Controller**: contains the code's logic
- **Policy**: contains the function called before the controller = middleware
- **Routes**: contains all the `*.json` routing configuration. You can create as many *.json files as you need. By default, all routes within a file look up the corresponding controller (= modules = controllers = middleware) inside the controller's default directory `./controller` (or within the directory specified by the user), which uses the following naming format: Route-name (without .json) + "Controller.js (the first letter must be capitalized)".

> **EXAMPLE:**
> If you have a definition file called `users.json`, by default the route searches the controller `UsersControllers.js`.
For routes *auth.json* all routes call the controller `AuthController.js` ecc.. ecc..

> **NOTE:**  this is a proposed structure but you can configure the module for your structure, you can change dir structure or add all routes in a single file.

### Creating JSON Configuration file
The routing file is encoded in the JSON format and by **default is in `./routes.`**

Router is created using this syntax:

`{ "RoutePath" : {"verb": {options} } }`

*Example of extended config*

```javascript
{
   "routePath": {
    "VERB": {
      "route": "controller:method",
      "policy": [
        "controller:method",
      ]
    }
  },

"/admin": {
    "GET": {
      "route": "action",
      "policy": [
        "./demo/policycustom/test:check",
        "test:all",
        "./subfolder/test2:index"
      ]
    },
    "POST": {
      "route": "./mycustomfolder/controllername:index",
      "policy": [
        "./demo/policycustom/test:check",
        "test:all",
        "./subfolder/test2:index"
      ]
    }
  },

...
  more routes
}
```

### RoutePath
This is the routing path and it follows the express4 standard routing. You can use jolly character and other type syntax `/admin*,` `/admin/:name` etc. etc.;

### Verb
Relates to the call verb and can assume any valid http verbs like GET, POST, PUT, DELETE etc etc. You can add more verbs for a single routePath:

```javascript
{
"/admin": {
    "GET": {
      "route": "action",
      "policy": [
        "./demo/policycustom/test:check",
        "test:all",
        "./subfolder/test2:index"
      ]
    },
    "POST": {
      "route": "action",
      "policy": [
        "test:all",
      ]
    }

}
```

`/admin` has GET and POST  verbs.

### Route

Relates to `file:method` to call a route address.

By default, the routing search controller file inside the default controller directory is: `./controlles`, and you can change it using the global options explained in this document.

If the controller is not set, the routing will search a file called with the same name as the json file, with "Controller" as suffix.

> **Example:**
> If you have a definition file called `users.json`, by default the route searches the controller `UsersControllers.json`.
For routes *auth.json* all routes call the controller `AuthController.js` etc.. etc..

**Summarize route params**

If you omit the route params, the system routing assumes you have a default route controller path/name and a method called "index".

If you add only a parameter, it assumes that the controller is in the default directory with standard name `nameController.js` , and the parameter is the method that should be called. example route: "testall"

If the route params contain both values `./path/controllername:method` (user:index) it will search the controller using the default directory path structured as controller name followed by method. For example, route: "./test/user:index" searches for a controller called ./test/user with method index.

If you **need to call a controller in a subfolder**, simply add the path before the controller name. Example route: "./afolder/user:index", fire ./controller/afolder/user with method index.

If you **need to call a controller starting to your project root** simply add `.` before the path. Example route: "./lib/user:index", fire  ./lib/user.js with method index.

### Policy

Is a module/function called before the controller (= middleware), by default it calls a file in ./policy named as you set in parameters "fileName" and a function named as you set in "functionName".

Example: policy: "auth/index" calls ./policy/auth.js and method index

**The syntax is the same as `route` params**

It can be a string for a single policy or an array for multiple policy files.

### CORS
Enable or disable Cross-origin resource sharing. default is true, look at global options for more info.

### Regex
You can set a regex to validate your route, however I discourage using it. Instead, I prefer to add this logic in the controller for better code speed. **To set a rexeg route, use the prefix "RE " before pattern.**.

```javascript
{
"RE /.*fly$/": {
    "GET": {
      "route": "action",
      "policy": [
        "./demo/policycustom/test:check",
        "test:all",
        "./subfolder/test2:index"
      ]
    }
}
```

### Init Module

Configure the routing modules in your main js file, as any other nodes modules.

```javascript
var routes = require('json-routing');
new routes.JsonRoute(expressApp, options).start();
```

Example:

```javascript
// Includes
var express     = require('express');
var app         = express();
var routes      = require('json-routing'); // add module

...

// your code..
app.set(...);
app.use(...);

// this is the magic!
new routes.JsonRoute(app, {
     "processdir": __dirname
}).start();

```

**IT'S VERY IMPORTANT TO SET `processdir": __dirname` if your project is in a subfolder of root. (example ./src/)**

Change default Options
-----------------
When you initialize the module, you can specify a few options to customize the directory structure.
All are listed below with the default values.  An explanation follows.

your main.js file.

```javascript
// Includes
var express     = require('express');
var app         = express();
var Routes      = require('json-routing'); // add module

// your code..
app.set(...);
app.use(...);

//define routes default options
var routeOptions = {
    routesPath      : "./api/routes",
    controllerPath  : "./api/controllers",
    policyPath      : "./api/policy",
    cors            : true,
    displayRoute    : true,
    defaultAction   : "index",
    processDir		: process.cwd()
}

//init routes
var routeInfo = new Routes.JsonRoute(app, routeOptions);
```

-  routesPath      : the path to your routes folder. `Default ./routes`
-  controllerPath  : the path to your controller folder. `Default ./controllers`
-  policyPath      : the path to your policy folder. `Default ./policy`
-  cors            : enable cross origin resource sharing for all routes. (more cors options coming soon..). `Default false`
-  displayRoute    : display in console loading route info, `default true`.
-  defaultAction   : the function called in route if not specified. It's not so useful, but it's here!.`Default index`
-  processDir		  : The root base path of the project, default `process.cwd()` set as `__dirname` if you need to start in a subfolder or complex project.

If you omit routeOptions or some params it use defaults values.

Change json file Global Options
-----------------
If you need to change options for all routes only for a specific *.json file, you can set in your file the key `GLOBAL` as in the following example:

user.json
```javascript
{
  "GLOBAL": {
    "controller": "./customdir/customControllerName",
    "policy":["config:setall","config:connection"],
    "baseUrl":"/user"
  },
   "/create": {
    "PUT": {
      "route": "index",
      "policy": [
        "auth:check",
        "auth:adduserparams"
      ]
    }
  }

}
```
Example: route controller is ./customdir/UserController.js

- controller: set a custom controller path for all routing file
- policy: is an array of policy `file:action` to fire before controller
- baseUrl: is a base path for all url routes in file. Example, inside a file all routes start with `/api/*`, i can set base url as `/api`. Now all file routes start with `/api`. If i have a routes `/users`, it fired when user called `/api/users`

> **NOTE:**  the key "GLOBAL" must be uppercase.

Full extended example
-----------------

*app.js*
```javascript
var express = require('express')
    , app = express()
    , port = process.env.PORT || 3000
    , routing = require('./lib/route');

/**
 * global options for routing
 *
 * set all file inside /api/* for a more cleaner code
 */
var routeOptions = {
    routesPath: "./api/routes"
    , controllersPath: "./api/controllers"
    , policyPath: './api/policy'
    , cors: false
    , processDir: __dirname
};

/**
 * init json-routing
 */
new routing.JsonRoute(app, routeOptions);

/**
 * standard express 4 routing
 * yes.. you can use both routing together if you need
 */
var router = express.Router();
router.get('/express/', function (req, res) {
    res.send(' this is a standard routing ');
});
app.use('/', router);

/**
 * server start
 *
 * @type {http.Server}
 */
var server = app.listen(port, function () {
    console.log('Listening on port %d', server.address().port);
});
```
This is the main file, we set routing and add global setting to use ./api as root directory

*./api/routes/users.json*
```javascript
{
   "/banned": {
    "GET": {
      "route": "./lib/bannedCustom:index",
      }
  },
   "/user": {
    "GET": {
      "route": "find",
      "policy": [
        "auth:check",
        "auth:adduserparams"
      ]
    },
     "PUT": {
      "route": "create",
      "policy": [
        "auth:check",
      ]
    }
  }

}
```
define the routes

*./api/controllers/UsersController.js*
```javascript
exports.index = function(req,res,next) {
    res.send(' index routes ');
};

exports.create = function(req,res,next) {
    res.send(' create routes params:'+req.params.name);
};
```
a basic controller logic

*./api/controllers/bannedCustom.js*
```javascript
exports.getbanned = function(req,res,next) {
    res.send(' custom controller name ');
};
```
this is the controller with custom name

*./api/policy/auth.js*
```javascript
exports.check = function(req,res,next) {
    if (!req.session.isLogged){
	     return  res.redirect('http://'+req.hostname+":3000/403");
    }
    next();
};
```
Let me explain this policy: it checks if a user is logged, else set a redirect, so we can use the middleware to check ACL, authorization or get/set global vars, and this is very useful.

Create a Policy File and Pass vars to controller
-----------------
We encourage to use standard tecnique for best performance: use middleware.
using the full example described below we can create a standard policy file to attach a global var using `req`

*./api/policy/auth.js*
```javascript
exports.getbanned = function(req,res,next) {
    if (!req.session.isLogged){
	     return  res.redirect('http://'+req.hostname+":3000/403");
    }
    //use req
    req.session.lastPing = new Date();
    next();
};
```

**Read the value in the controller or policy**

*./api/controllers/bannedCustom.js*
```javascript
exports.getbanned = function(req,res,next) {
    res.send(' custom controller name, middleware loaded at: '+req.session.lastPing);
};
```

Case: using middleware
-----------------

A special case: if we want to add an authentication before some route, take a look at this example:

```javascript
{

"/admin": {
    "GET": {
      "route": "index",
       "policy":["auth:check"]
     }
  }
}}
```
All `/dadmin` route calls the controller `auth`, so now `auth:check` is executed before all `index` function and it becomes
 a policy (=middleware) and for a clear structure i put the file in policy dir.

An alternative example use the global file option, all routes inside use "auth:check" middleware:

```javascript
{
 "GLOBAL": {
    "policy":["auth:check"],
    "baseUrl":"/admin"
  },
  
   "/dashboard": {
    "GET": {
      "route": "getItem",
      }
  },
   "/user": {
    "GET": {
      "route": "find",
    },
     "PUT": {
      "route": "create",
    }
  }

}}
```

Protected route with JWT
-----------------
You can protect a routes using [jwt](https://jwt.io/). Json-routing use [auth0/express-jwt](https://github.com/auth0/express-jwt).
To protect a route add a property `jwt:true` and set the global options for jwt as example.

**Before using jwt you need to install express-jwt manually: `npm install --save express-jwt`**

*Route file: protected.json* 
 
```  
{
  "/protected": {
    "GET": {
      "route": "index",
      "jwt": true
    }
  },
  "/notprotected": {
    "GET": {
      "route": "indexnot",
      "jwt": false
    }
  }
}
  
```
NB note to pretect a route we need to set `jwt:true`

In main file: server.ts/js

```  
...

export const routeInfo: Array<IRouteInfo> = new JsonRoute(app, {
    "processdir": __dirname,
    "jwt": {
        "secret": "12345678910abc"
    }
}).start();

...

```
NB in json-routing init we need to set jwt object with secret

DONE!!!!!

### jwt extra route for error
to make a better jwt unauthorized response we can add a specific route like this:

```
export const routeInfo: Array<IRouteInfo> = new JsonRoute(app, {
    "processdir": __dirname,
    "jwt": {
        "secret": "12345678910abc"
    }
}).start();

app.use((err: any, req: express.Request, res: express.Response, next: express.NextFunction) => {
    if (err.name === 'UnauthorizedError') {
        res.status(401).json({"message": "invalid token..."});
    }

next();
});

```

Add a global route prefix
-----------------
You can add a global prefix path for all routes set options.urlPrefix

```
export const routeInfo: Array<IRouteInfo> = new JsonRoute(app, {
    "processdir": __dirname,
    "urlPrefix":"/api/v1"
   
}).start();

```
All routes now start with `/api/vi`

Route validation params
-----------------
It can be done by express-validator using schema. Add `validators` object with:

- params -> route params es /home/:id
- query  -> query params es -> /home?id=124
- boby   -> body params es post params like {"id":"1233"}

according [express-validator](https://github.com/ctavan/express-validator) "validation by Schema"

route file.json

```
{
  "/validateparam/:id": {
    "GET": {
      "route": "validateparam",
      "jwt": false,
      "validators": {
        "params": {
          "id": {
            "notEmpty": true,
            "isLength": {
              "options": [
                {
                  "min": 5,
                  "max": 10
                }
              ],
              "errorMessage": "Must be between 2 and 10 chars long"
            },
            "errorMessage": "id is required"
          }
        }
      }
    }
  }
}

```
**NB body-parser middleware is injected by json-routing, you can pass params in global params**

ALL OPTIONS
-----------------
```javascript
export interface IOptions {
    routesPath?: string
    , controllersPath?: string
    , policyPath?: string
    , processdir?: string
    , cors?: boolean
    , displayRoute?: boolean
    , defaultAction?: string
    , urlPrefix?: string
    , jwt?: {
        secret: any
    }
    , bodyParserUrlEncoded?: any
}

...

let options: IOptions;

...
// add params to optins object

let routeInfo:Array<any> = new Routes.JsonRoute(app, options}).start();

```

Example
-----------------
Look at ./demo for a fully working example.

Changelog
-----------------
Check git [release history](https://github.com/gimox/json-routing/releases)

json-routing

json-routing Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

json-routing

json-routing Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README