meta-controller v2.0.2

What is meta-controller?

meta-controller is a library for creating NodeJs REST APIs using TypeScript decorators. It is a wrapper for the popular express framework. It's designed to be a lightweight alternative to NestJs.

Installation

Install the meta-controller package from npm. npm install meta-controller

Basic Usage

Create a REST API controller by using the JsonController(<route>) decorator and define routes by using the @Route(<http method>, <path>) decorator. Routes can be synchronous or asynchronous. Route paramaters are automatically transformed (meta-transformer) and validated (meta-validator).

@JsonController("/basic")
class WidgetController {
    @Route(HttpMethod.GET)
    get(): Widget {
        return testWidget;
    }
}

const expressApp = express();
MetaController.useExpressServer(expressApp, {
    isUseCors: true,
    controllerClassTypes: [
        WidgetController
    ]
});
apiServer = http.createServer(expressApp);
apiServer.listen(4500);

Initialization

Pass an instance of express to MetaController.useExpressServer() to initialize meta-controller.

const expressApp = express();
MetaController.useExpressServer(expressApp, {
    // options
});

The following initialization options are available.

Route Parameters

Controllers may accept all standard REST type parameters. Parameters are automatically transformed or cast to the specified type.

HTTP Request Body

@Route(HttpMethod.POST, "/body")
myRoute(@Body() widget: Widget) {
    // ... business logic
}

Route Parameters

// Example: https://localhost/api/param/5
@Route(HttpMethod.GET, "/param/:id")
myRoute(@Param("id") id: number) {
    // ... business logic    
}

Route Query Parameters

// Example: https://localhost/api/query-param?myQueryParam=test
@Route(HttpMethod.POST, "/query-param")
myRoute(@QueryParam("myQueryParam") myQueryParam: string) {
    // ... business logic    
}

HTTP Request Headers

@Route(HttpMethod.GET, "/header-param")
myRoute(@HeaderParam("TestHeader") testHeader: string) {
    // ... business logic    
}

Authorization

You can require authorization on a per-controller basis by specifying an authorizationHandler() and using the @Authorization() decorator.

const expressApp = express();
MetaController.useExpressServer(expressApp, {
    authorizationHandler: (request, response, roles): boolean => {
        // ... business logic
        // Return true for authorized, false for unauthorized
        return true;
    }
});

@Authorize(["Admin"])
@JsonController("/secure")
class SecureController {
    @Route(HttpMethod.GET, "/protected-route")
    myRoute() {
        // ... business logic
    }
}

If you also add a currentUserHandler() you can inject the current user using the CurrentUser() decorator.

class User {
    userName: string = "TestUser";
}
const testUser = new User();

const expressApp = express();
MetaController.useExpressServer(expressApp, {
    currentUserHandler: (request, response): User => {
        // ... business logic
        return testUser;
    }
});

@Route(HttpMethod.GET, "/current-user")
getCurrentUser(@CurrentUser() currentUser: User): User {
    // ... business logic
    return currentUser;
}

Error Handling

You can throw errors along with associated HTTP error codes.

@Authorize(["Admin"])
@JsonController("/secure")
class SecureController {
    @Route(HttpMethod.GET, "/protected-route")
    myRoute() {
        throw new HttpError(HttpStatus.UNAUTHORIZED, "Unauthorized request");
    }
}

If no HTTP error code is specified then meta-controller defaults to using HTTP status 500 (INTERNAL_SERVER_ERROR).

@Route(HttpMethod.POST, "/body")
myRoute(@Body() widget: Widget) {
    // Returns HTTP status 500 - INTERNAL_SERVER_ERROR
    throw new Error("An unknown error occurred");
}

Decorator Reference