Express Decorated Router

Define your Express routes in a nice, expressive way using TypeScript decorators!

---

Table of Contents

• Basic usage
• API
  • Decorators
    • ALL(path: PathParams)
    • Controller(root?: string, options?: RouterOptions)
    • ControllerMiddleware(first: RequestHandler, ...middleware: RequestHandler[])
    • DELETE(path: PathParams)
    • GET(path: PathParams)
    • HEAD(path: PathParams)
    • Method(httpMethod: string, path: PathParams)
    • OPTIONS(path: PathParams)
    • PATCH(path: PathParams)
    • POST(path: PathParams)
    • PUT(path: PathParams)
    • Parent(parentController: Function)
    • RouteMiddleware(first: RequestHandler, ...middleware: RequestHandler[])
  • Classes
    • ExpressDecoratedRouter
      • public static applyRoutes(app: IRouter)
      • public static reset()
    • ParentControllerError
      • public child
      • public parent
    • UnregisteredControllerError
      • public controller
• Example app
• Common problems
  • Routes do not get registered
• Good practices

Basic usage

import * as express from 'express';
import {Controller, ControllerMiddleware, POST, RouteMiddleware, ExpressDecoratedRouter} from 'express-decorated-router';

@Controller('/auth')
@ControllerMiddleware(someMiddleware(), moreMiddleware())
class MyAuthController {

  @POST('/login')
  @RouteMiddleware(onlyApplyToThisRoute())
  public static login(req: express.Request, res: express.Response): void {
    doSomeMagic();
  }
}

const app: express.Application = express();

ExpressDecoratedRouter.applyRoutes(app);
ExpressDecoratedRouter.reset();

API

Decorators

ALL(path: PathParams)

Use this handler for any HTTP method

Returns: MethodDecorator

Parameters

	Type	Required	Description
path	PathParams	:heavy_check_mark:	The path this handler will be responsible for

Defined in decorators/method/ALL.ts:8

---

Controller(root?: string, options?: RouterOptions)

Register this class as a controller

Returns: ClassDecorator

Parameters

	Type	Required	Default value	Description
root	string	:x:	"/"	The root path for this controller
options	RouterOptions	:x:		Options passed to the Express router initialisation function.

Defined in decorators/Controller.ts:9

---

ControllerMiddleware(first: RequestHandler, ...middleware: RequestHandler[])

Define middleware for this controller. Any child controller which defines this class as its @Parent will inherit this middleware.

Returns: ClassDecorator

Parameters

	Type	Required	Description
first	RequestHandler	:heavy_check_mark:	A middleware handler
middleware	RequestHandler[]	:x:	0..n additional middleware handlers

Defined in decorators/ControllerMiddleware.ts:10

---

DELETE(path: PathParams)

Use this handler for the DELETE HTTP method

Returns: MethodDecorator

Parameters

	Type	Required	Description
path	PathParams	:heavy_check_mark:	The path this handler will be responsible for

Defined in decorators/method/DELETE.ts:8

---

GET(path: PathParams)

Use this handler for the GET HTTP method

Returns: MethodDecorator

Parameters

	Type	Required	Description
path	PathParams	:heavy_check_mark:	The path this handler will be responsible for

Defined in decorators/method/GET.ts:8

---

HEAD(path: PathParams)

Use this handler for the HEAD HTTP method

Returns: MethodDecorator

Parameters

	Type	Required	Description
path	PathParams	:heavy_check_mark:	The path this handler will be responsible for

Defined in decorators/method/OPTIONS.ts:8

---

Method(httpMethod: string, path: PathParams)

Use this handler for the given HTTP method. The method must be one understood by Express' router.METHOD() method

Returns: MethodDecorator

Parameters

	Type	Required	Description
httpMethod	string	:heavy_check_mark:	The HTTP method
path	PathParams	:heavy_check_mark:	The path this handler will be responsible for

• See: https://expressjs.com/en/4x/api.html#router.METHOD

Defined in decorators/method/Method.ts:10

---

OPTIONS(path: PathParams)

Use this handler for the OPTIONS HTTP method

Returns: MethodDecorator

Parameters

	Type	Required	Description
path	PathParams	:heavy_check_mark:	The path this handler will be responsible for

Defined in decorators/method/HEAD.ts:8

---

PATCH(path: PathParams)

Use this handler for the PATCH HTTP method

Returns: MethodDecorator

Parameters

	Type	Required	Description
path	PathParams	:heavy_check_mark:	The path this handler will be responsible for

Defined in decorators/method/PATCH.ts:8

---

POST(path: PathParams)

Use this handler for the POST HTTP method

Returns: MethodDecorator

Parameters

	Type	Required	Description
path	PathParams	:heavy_check_mark:	The path this handler will be responsible for

Defined in decorators/method/POST.ts:8

---

PUT(path: PathParams)

Use this handler for the PUT HTTP method

Returns: MethodDecorator

Parameters

	Type	Required	Description
path	PathParams	:heavy_check_mark:	The path this handler will be responsible for

Defined in decorators/method/PUT.ts:8

---

Parent(parentController: Function)

Define another controller as this controller's parent, inheriting its root path and middleware.

Returns: ClassDecorator

Parameters

	Type	Required	Description
parentController	Function	:heavy_check_mark:	The parent controller

Defined in decorators/Parent.ts:7

---

RouteMiddleware(first: RequestHandler, ...middleware: RequestHandler[])

Define middleware for this route

Returns: MethodDecorator

Parameters

	Type	Required	Description
first	RequestHandler	:heavy_check_mark:	A middleware handler
middleware	RequestHandler[]	:x:	0..n additional middleware handlers

Defined in decorators/RouteMiddleware.ts:9

---

Classes

ExpressDecoratedRouter

Public interface for the express-decorated-router library

Defined in ExpressDecoratedRouter.ts:42

public static applyRoutes(app: IRouter)

Apply routes to the Express application. You should call reset() after calling this.

Returns: ExpressDecoratedRouter

Parameters

	Type	Required	Description
app	IRouter	:heavy_check_mark:	The Express application

• Throws: {ParentControllerError} If the input of a @Parent decoration has not been decorated with @Controller
• Throws: {UnregisteredControllerError} If a class decorated with @Parent was not annotated with @Controller

Defined in ExpressDecoratedRouter.ts:139

public static reset()

Reset the library, freeing resources. You should call this method after calling applyRoutes()

Returns: ExpressDecoratedRouter

Defined in ExpressDecoratedRouter.ts:155

---

ParentControllerError

Thrown when an input of a @Parent decoration has not been decorated with @Controller

Extends: Error

Defined in errors/ParentControllerError.ts:4

public child

The child controller

Defined in errors/ParentControllerError.ts:6

public parent

The parent controller

Defined in errors/ParentControllerError.ts:8

---

UnregisteredControllerError

Thrown when a class decorated with @Parent was not annotated with @Controller

Extends: Error

Defined in errors/UnregisteredControllerError.ts:4

public controller

The controller

Defined in errors/UnregisteredControllerError.ts:6

---

Example app

An example app can be found in the example directory.

Common problems

Routes do not get registered

You must import/require the files containing your routes before you call applyRoutes(). When in doubt, set the DEBUG environment variable to express-decorated-router and see exactly what's going on.

Good practices

• Always call ExpressDecoratedRouter.reset() after applying your routes to free up resources