express_annotations v0.1.1
express-annotations
Annotation for express with typescript
installations
npm install --save express_annotationshow to use it
With the AbstractExpressServer
You only need to extend the AbstractExpressServer
import {AbstractExpressServer} from "express_annotations/dist/AbstractExpressServer";
import * as bodyParser from "body-parser";
export class Server extends AbstractExpressServer {
// This method is called from the abstract class
// to allow you to add custom use as bodyParser
protected doPrepareApp(): void {
this.app.use(bodyParser.json());
this.app.use(bodyParser.urlencoded({ extended: false }));
}
// when the express app is ready this handler is called
protected listenHandler () : void {
console.log ("Express ready");
}
// called if an error happend when initializing app
protected initError(error: any): void {
console.log("Error happen !", error);
}
}Then in a bin.ts file
import {Server} from "./Server";
let server = new Server(3000);
// the method loadController is to loadControllers
// it accepts regexp and return a native promise
// Be cause the loadController method is asynchrone, the method listen will be called
// only when all the controllers are loaded
server.prepareApp().loadController("./controllers/*.js").listen();Then you need to configure your controller.
With annotation
If you don't want to use the Abstract Class what you need to do is to create a class then add the @ExpressApp annotation on your express app.
import * as express from "express";
export class Server {
@ExpressApp
app = express ();
}Routing
For routing you only need to add an annotation on your routing class and implements IRoute :
import * as express from "express";
import {IRoute, Router} from "express_annotations/dist/ExpressAnnotations";
@Router({route: "/example"})
export class Test implements IRoute {
// the router is automatically set by the annotation
router : express.Router;
}By this way you have access to the controller so if you want to manipulate some rules using the express router, you still can.
====\ When using the AbstractController the method loadController will try to make a new on every function exported in the module (Class are converted as function)
handling call
GET / POST / PATCH / PUT / DELETE
All the method are accessible by annotation inside your Routing class.\ All method work with promise so you need to return a promise with your result.\ You can either return a couple of header / body, an object or a status
GET
@Router({route: "/example"})
export class Test implements IRoute {
// the router is automatically set by the annotation
router : express.Router;
// json:true means you want express return as json
@GET({path:"/json", json:true})
private handleGet () {
return Promise.resolve({hello:"world !"});
}
// status:true means you want express return as response.sendStatus (status)
@GET({path:"/status", status:true})
private handleStatus () {
return Promise.resolve(200);
}
// no status and no json mean you send your result as it is : response.send ("Hello world")
@GET({path:"/plain"})
private handleStatus () {
return Promise.resolve("Hello world");
}
// By this way you can send custom header
@GET({path:"/customHeader", json:true})
private handleStatus () {
return Promise.resolve({header:{"custom-header":"hello header !"}, body:{result:"Hello world with custom headers"});
}
}POST
@Router({route: "/example"})
export class Test implements IRoute {
// the router is automatically set by the annotation
router : express.Router;
...
@POST ({path="/", json:true})
private handlePost (@body body : any) {
return Promise.resolve ({sendBody:body});
}
}PATCH
@Router({route: "/example"})
export class Test implements IRoute {
// the router is automatically set by the annotation
router : express.Router;
...
@PATCH ({path="/", json:true})
private handlePatch (@body body : any) {
return Promise.resolve ({method:"patch", sendBody:body});
}
}PUT
@Router({route: "/example"})
export class Test implements IRoute {
// the router is automatically set by the annotation
router : express.Router;
...
@PUT ({path="/", json:true})
private handlePut (@body body : any) {
return Promise.resolve ({method:"put", sendBody:body});
}
}DELETE
@Router({route: "/example"})
export class Test implements IRoute {
// the router is automatically set by the annotation
router : express.Router;
...
@DELETE ({path="/", json:true})
private handleDelete () {
return Promise.resolve ({method:"delete"});
}
}Parameters
To get headers, path params or queries you only need to annotate your method arguments
@Router({route: "/example"})
export class Test implements IRoute {
// the router is automatically set by the annotation
router : express.Router;
...
@GET ({path="/:id", json:true})
private handleFindById (@param("id") id : string) {
return Promise.resolve ({method:"findById", id:id});
}
@GET ({path="/", json:true})
private handleFindByQueryId (@query("id") id : string) {
return Promise.resolve ({method:"findByQueryId", id:id});
}
@GET ({path="/byHeader", json:true})
private handleFindByHeaderId (@EHeader("id") id : string) {
return Promise.resolve ({method:"findByHeaderId", id:id});
}
// if no name is given all headers will be returned
@GET ({path="/byHeader2", json:true})
private handleFindByCustomProp (@EHeader() headers : any) {
return Promise.resolve ({method:"handleFindByCustomProp", id:headers["id"]});
}
}If you override the express request and need a property inside the request you can also need the @custom annotation
@Router({route: "/example"})
export class Test implements IRoute {
// the router is automatically set by the annotation
router : express.Router;
...
@GET ({path="/byHeader", json:true})
private handleFindByCustomProp (@custom("myCustomProp") myCustomProp : any) {
return Promise.resolve ({method:"handleFindByCustomProp", myProp:myCustomProp});
}
}Finaly if you want to have the orignal express Request and Response
@Router({route: "/example"})
export class Test implements IRoute {
// the router is automatically set by the annotation
router : express.Router;
...
// the noResponse: true is to avoid to send response twice
@GET ({path="/byOldSchool", noResponse:true})
private handleOldSchool (@ERequest() request : Request, @EResponse() response : Response) {
response.json ({oldSchool:true, response:"Hello world !"});
return Promise.resolve ();
}
}Automatic Path, Params and Query
If you don't specify name or path, annotations system will automatically handle them by the method or arguments name
@Router({route: "/example"})
export class Test implements IRoute {
// the router is automatically set by the annotation
router : express.Router;
...
// the generated path will be "<host>:<port>/example/automaticPath/:name"
// For example http://localhost:3000/example/automaticPath/foo?start=25
// will result to a call with name=foo and start = 25
@GET ({json:true})
private automaticPath (@param name:string, @query start : number) {
return Promise.resolve ({method:"automaticPath", name:name, start: start});
}
}Error Handling
Route Error Handling
You can ser error handler for a local router with the @ErrorHandler annotation :
@Router({route: "/example"})
export class Test implements IRoute {
// the router is automatically set by the annotation
router : express.Router;
...
@ErrorHandler
private errorHandler (error : any, req : Request, res : Response, next : NextFunction) {
console.log ("Error handling from route 'example'");
res.status(500);
res.json(error);
}
}Global Error Handling
Because the error method in express have to be set as the last use method, we only manage to add it in the helper AbstractExpressServer.
If you are using this helper you can leave the default method provided or override the method errorHandler
This is the default behaviour :
protected errorHandler (error : any, req : Request, res : Response, next : NextFunction) {
let status = error.status || 500;
let err = error.error || error;
res.status(status);
if (typeof err == "object")
res.json(err);
else {
res.send(err);
}
}