@universal-packages/express-controllers
v1.12.6
Published
Express app builder based on decorated controller classes
Downloads
7,434
Readme
Express Controllers
Express app builder based on decorated controller classes.
Install
npm install @universal-packages/express-controllers
npm install express
# Optional as needed
npm install cookie-parser
npm install cors
npm install helmet
npm install pug
ExpressControllers
Express app is the main interface to build an express app from the decorated controllers and also start running a web server.
import { ExpressControllers } from '@universal-packages/express-controllers'
const expressControllers = new ExpressControllers({ appLocation: './src', port: 3000 })
// Load decorated controllers and middleware
await expressControllers.prepare()
await expressControllers.run()
// Once finishing
await expressControllers.stop()
Options
ExpressControllers
takes as options the same ListenOptions from net, additionally takes the following ones:
appLocation
String
Where should we look for controllers and middleware and load them?bodyParser
'json' | 'raw' | 'text' | 'urlencoded' | 'none' | ('json' | 'raw' | 'text' | 'urlencoded')[]
What body parser or body parsers use across the appcors
CorsOptions | true
Enable cors for this app, optionally passing CorsOptionscookieParser
CookieParseOptions | true
Enable cookie parser for this app, optionally passing CookieParseOptionshelmet
HelmetOptions | true
Enable helmet for this app, optionally passing HelmetOptionsviewEngine
String
Sets the view renderer (template engines)
BaseController
Use the base controller Class to enable your controller to use some goodies. It implement almost the same functionally as the response object so instead of doing response.something()
you can directly call your controller instance.
import { BaseController } from '@universal-packages/express-controllers'
export default class AuthController extends BaseController {
async index() {
this.status('OK').send('HOLA')
}
}
Decorators
Decorate your controller classes to enable them to respond to requests.
@Controller([path: string, options])
Registers a class to behave as a controller. To be able to access this.request
and this.response
inside your controller actions you can extend your controller with the BaseController
, it is not necessary but useful to access those object that way instead of using Argument Decorators
.
Controllers need to export the controller class as the default module in order to all work correctly.
arguments
path
String
default: /
This is the equivalent in pure express to:app.use($path, router)
, internally you can see a controller as an express router object so this path will be prepended to all routes.options
Map
bodyParser
'json' | 'raw' | 'text' | 'urlencoded' | 'none' | ('json' | 'raw' | 'text' | 'urlencoded')[]
What body parser use across this particular controller, usenone
to disregard any body parser for this controller.
import { BaseController, Controller } from '@universal-packages/express-controllers'
@Controller('/auth', { bodyParser: 'json' })
export default class AuthController extends BaseController {}
@ControllerUse(middleware, [options])
Enables a middleware to execute before all controller actions.
arguments
middleware
Middleware
A middleware function or middleware classoptions
Map
Any options the middleware may be prepared to receive (Class middleware)
import { BaseController, Controller, ControllerUse } from '@universal-packages/express-controllers'
import RoleMiddleware from './RoleMiddleware'
@Controller('/auth', { bodyParser: 'json' })
@ControllerUse(RoleMiddleware, { roles: ['admin'] })
export default class AuthController extends BaseController {}
@Action(method: HTTPVerb, path: string, [options])
Enables a controller instance method to be called when the route matches.
arguments
method
'DELETE' | 'GET' | 'HEAD' | 'OPTIONS' | 'PATCH' | 'POST' | 'PUT'
The instance method will be called if the request method matches the configured one.path
String
Path to match to call this instance method, ex:/users
orusers/:id
options
Map
bodyParser
'json' | 'raw' | 'text' | 'urlencoded' | 'none' | ('json' | 'raw' | 'text' | 'urlencoded')[]
default: json
What body parser to use for this particular action, usenone
to disregard any body parser for this action.
import { Action, BaseController, Controller } from '@universal-packages/express-controllers'
@Controller('/auth', { bodyParser: 'json' })
export default class AuthController extends BaseController {
@Action('GET', { bodyParser: 'text' })
async root() {
this.response.send('Hola')
}
@Action('POST', '/login', { bodyParser: 'json' })
async login() {
const body = this.request.body
this.response.send(`login with ${JSON.stringify(body)}`)
}
@Action('POST', '/signup')
async signup() {
const body = this.request.body
this.response.send(`signup with ${JSON.stringify(body)}`)
}
}
Fast equivalents
The following decorators behave the same as @Action
the only difference is that they don't take the first argument since the decorator name describe the action method itself.
@Delete(path: string, [options])
@Head(path: string, [options])
@Patch(path: string, [options])
@Post(path: string, [options])
@Put(path: string, [options])
import { BaseController, Controller, Get, Post } from '@universal-packages/express-controllers'
@Controller('/auth', { bodyParser: 'json' })
export default class AuthController extends BaseController {
@Get()
async root() {
this.response.send('Hola')
}
@Post('/login')
async login() {
const body = this.request.body
this.response.send(`login with ${JSON.stringify(body)}`)
}
@Post('/signup')
async signup() {
const body = this.request.body
this.response.send(`signup with ${JSON.stringify(body)}`)
}
}
@ActionUse(middleware: Middleware, [options])
Enables a middleware to execute before a specific action.
arguments
middleware
Middleware
A middleware function or middleware classoptions
Map
Any options the middleware may be prepared to receive (Class middleware)
import { ActionUse, BaseController, Controller, Get } from '@universal-packages/express-controllers'
import SecureMiddleware from './SecureMiddleware'
@Controller('/auth', { bodyParser: 'json' })
export default class AuthController extends BaseController {
@Get()
@ActionUse(SecureMiddleware, { sometimes: true })
async root() {
this.response.send('Hola')
}
}
Arguments Decorators
You can simplify the code inside your actions by using argument decorators to get certain info from the request.
@Body()
Gets the request body.async login(@Body() body) { this.response.json({ body }) }
@Header(name:string)
Gets a specific header form the request header.async login(@Header('Authentication') header) { this.response.json({ header }) }
@Headers()
Gets the whole headers object form request.async login(@Headers() headers) { this.response.json({ headers }) }
@Param(name:string)
Gets a specific param parsed for the request.async login(@Param('id') id) { this.response.json({ id }) }
@Params()
Gets the whole params parsed object from the request.async login(@Params() params) { this.response.json({ params }) }
@Res()
Gets the whole response object.async login(@Res() response) { response.json({ argument: 'yes' }) }
@Req()
Gets the whole request object.async login(@Req() request) { const body = request.body response.json({ argument: 'yes', body }) }
@Query([name: string])
Gets the whole query object or a specific property in it.async login(@Query() query, @Query('ordered') ordered) { this.response.json({ query, ordered }) }
BaseMiddleware
Use the base middleware Class to enable your middleware to use some goodies. It implement almost the same functionally as the response object so instead of doing response.something()
you can directly call your middleware instance.
import { BaseMiddleware } from '@universal-packages/express-controllers'
export default class AuthMiddleware extends BaseMiddleware {
async middleware() {
this.status('OK').send('HOLA')
}
}
Ending responses
When using class middleware if the middleware ends the equest, the next()
chain is broken automatically and the request will not reach further more.
import { BaseMiddleware } from '@universal-packages/express-controllers'
export default class AuthorizationMiddleware extends BaseMiddleware {
async middleware() {
this.status('UNAUTHORIZED').end()
}
}
@Middleware()
Registers a class to behave as a middleware. To be able to access this.request
and this.response
and this.options
inside your middleware action you can extend your controller with the BaseMiddleware
, is not necessary but useful to access those object that way instead of using Argument Decorators
.
Middleware need to export the middleware class as the default module in order to all work correctly.
import { BaseMiddleware, Middleware } from '@universal-packages/express-controllers'
import createHttpError from 'http-errors'
import { StatusCodes } from 'http-status-codes'
@Middleware()
export default class AuthMiddleware extends BaseMiddleware {
async middleware() {
if (!this.request['user']) throw createHttpError(StatusCodes.UNAUTHORIZED)
}
}
Middleware Arguments Decorators
Middleware actions can use all the Argument Decorators
plus one more to access middleware options.
@MiddlewareOptions()
Gets the options passed to this middleware through@ControllerUse()
or@ActionUse()
@Middleware() export default class AuthMiddleware extends BaseMiddleware { async middleware(@Request() request, @MiddlewareOptions() options) { if (options.sometimes && Math.random() > 0.5) { if (!request['user']) throw createHttpError(StatusCodes.UNAUTHORIZED) } } }
Global middleware
In order to apply middleware to the whole app globally, you need to prefix your middleware files with .middleware
.
Recommended structure:
- src
|_ middleware
|_ TopLevel.middleware.js|ts
|_ top.middleware.js|ts
|_ controllers
By default global middleware is applied to the express app as any other to level middleware like cors
or helmet
but you can configure your global middleware to run individually alongside each action by defining the static property strategy
to each
. Then the middleware will run just after the body parser is applied and before the controller an action middleware.
@Middleware()
export default class AuthMiddleware extends BaseMiddleware {
public static readonly strategy = 'each' // default 'global'
async middleware(@Request() request, @MiddlewareOptions() options) {
if (options.sometimes && Math.random() > 0.5) {
if (!request['user']) throw createHttpError(StatusCodes.UNAUTHORIZED)
}
}
}
Middleware as functions
You can use middleware as a pure RequestHandler
function in both top level middleware and middleware passed through @ControllerUse()
or @ActionUse()
.
export default function top(request, response, next) {
request.context = {}
next()
}
Global middleware as function will always run globally and can not be configured to run alongside actions.
Events
ExpressControllers
will emit events regarding request being processed.
expressControllers.on('request:start', (event) => console.log(event))
expressControllers.on('request:not-found', (event) => console.log(event))
expressControllers.on('request:error', (event) => console.log(event))
expressControllers.on('request:middleware', (event) => console.log(event))
expressControllers.on('request:handler', (event) => console.log(event))
expressControllers.on('request:end', (event) => console.log(event))
expressControllers.on('warning', (event) => console.log(event))
Typescript
This library is developed in TypeScript and shipped fully typed.
Contributing
The development of this library happens in the open on GitHub, and we are grateful to the community for contributing bugfixes and improvements. Read below to learn how you can take part in improving this library.