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