Project implements decorators for modern tools for NodeJS like:

ExpressJS

Installation


npx create-air-api new

Note:

Please Start in development mode and then buildit, if you get an error on dev mode that is because .ts files are not available to the controllers.

API

Decorators

Class

@Controller(baseUrl: string, middleware?: Middleware[]), @Controller(baseUrl: string, routerOptions: RouterOptions, middleware?: Middleware[]) - Registers controller for base url

Method

@All(url: string, middleware?: Middleware[]) - Registers all routes
@Get(url: string, middleware?: Middleware[]) - Registers get route
@Post(url: string, middleware?: Middleware[]) - Registers post route
@Put(url: string, middleware?: Middleware[]) - Registers put route
@Delete(url: string, middleware?: Middleware[]) - Registers delete route
@Patch(url: string, middleware?: Middleware[]) - Registers patch route
@Options(url: string, middleware?: Middleware[]) - Registers options route
@Head(url: string, middleware?: Middleware[]) - Registers head route
@Status(code: number) - Specifies status code for the route

where middleware is the class that implements Middleware interface.

To use class, import Middleware interface and implement it, like so:

import { Middleware } from "@/modules/app";

class UserMiddleware implements Middleware {
  public use(request: Request, response: Response, next: NextFunction): void {
    next();
  }
}

or a simple function

function userMiddleware(
  request: Request,

  response: Response,

  next: NextFunction
): void {
  next();
}

Parameter

@Request(property?: string) (alias @Req(property?: string)) - Returns express req object or any other object, if name was specified
@Response() (alias @Res) - Returns express res object
@Next() - Returns express next function
@Params(param?: string) - Express req.params object or single param, if param name was specified
@Query(param?: string) - Express req.query object or single query param, if query param name was specified
@Body(param?: string) - Express req.body object or single body param, if body param name was specified
@Headers(property?: string) - Express req.headers object or single headers param, if headers param name was specified
@Cookies(param?: string) - Express req.body object or single cookies param, if cookies param name was specified

Error middleware

To add error middleware, that handles unhandled errors simply implement ErrorMiddleware interface and provide it using ERROR_MIDDLEWARE token, like so:

import { Container, ErrorMiddleware, ERROR_MIDDLEWARE } from "@/modules/app";

@Injectable()
class ServerErrorMiddleware implements ErrorMiddleware {
  public use(
    error: Error,

    request: Request,

    response: Response,

    next: NextFunction
  ) {
    next();
  }
}

Container.provide([
  { provide: ERROR_MIDDLEWARE, useClass: ServerErrorMiddleware },
]);

or as a function

import { Container, ERROR_MIDDLEWARE } from "@/modules/app";

function serverErrorMiddleware(
  error: Error,

  request: Request,

  response: Response,

  next: NextFunction
) {
  next();
}

Container.provide([
  { provide: ERROR_MIDDLEWARE, useValue: serverErrorMiddleware },
]);

Dependency injection

This module supports dependency injection provided by module. For example, see the full example below.

Use `@Injectable()` on class which u want to use in controllers or services.

By Default all file in directory controllers and services are auto loaded. Files other than services with @Injectable() decorator must be provide in ./src/services/index.ts

//fileContent ./src/services/index.ts
import { DependencyManager } from "@/modules/common/dependencies";
import { ERROR_MIDDLEWARE } from "@/modules/app";
import { ServerErrorHandler } from "@/middlewares";
import { ClassConstructor, ClassProvider } from "@/modules/common/types";
import { Helpers } from "@/lib/helpers";
import { FilesMapper } from "@enjoys/express-utils/file-mapper";

// Add your custom services here
const YourDependency = [Helpers];

export const RegisterDependencies = async () => {
  const ServiceArray = await FilesMapper.forRoot(
    "./build/src/services/**/*.service.js"
  );
  const Services: Array<ClassConstructor | ClassProvider> = [
    ...ServiceArray,
    ...YourDependency,
    { provide: ERROR_MIDDLEWARE, useClass: ServerErrorHandler },
  ];
  return DependencyManager.imports(Services);
};

Example Express Application and Controller:

import {
  Response,
  Params,
  Controller,
  Get,
  attachControllers,
  Middleware,
} from "@/modules/app";

@Controller("/")
class UsersController {
  constructor(private userService: UserService) {}

  @Get("/users/:id")
  getData(@Response() res, @Params("id") id: string) {
    res.send(this.userService.findById(id));
  }
}

let app = express();

attachControllers(app, [UsersController]);

app.listen(3000);

You can also attach controllers to express.Router instance. This is useful when you want to namespace all of the routes with a prefix:

import { attachControllers } from "@/modules/app";
const apiRouter = express.Router();
const controllers = await FilesMapper.forRoot("./build/src/contollers/**/*.js");
await attachControllers(apiRouter, controllers);
app.use("/v1/api", apiRouter);

You can also use custom decorators as middleware :

Custom Decorator

import { attachMiddleware } from "@/modules/app";

import { Request, Response, NextFunction } from "express";

export function Access(key: string) {
  return function (
    target: any,

    propertyKey: string,

    descriptor: PropertyDescriptor
  ) {
    attachMiddleware(
      target,

      propertyKey,

      (req: Request, res: Response, next: NextFunction) => {
        if (["CAN_ACCESS_TEST", "CAN_ACCESS_HOME"].includes(key)) {
          next();
        } else {
          res.send("ACCESS DENIED");
        }
      }
    );
  };
}

Controller Code

@Controller("/")
export class MainController {
  @Access("CAN_ACCESS_TEST")
  @Get("/test")
  getB() {
    return "You can access the test";
  }

  @Access("CAN_ACCESS_HOME")
  @Get("/home")
  getB() {
    return "You can access the home";
  }
}

Note:- Please use custom decorators before express decorators otherwise system will not detect any controller metadata and your decorator will not invoked.

Will work:

@Access("CAN_ACCESS_TEST")

@Get("/test")

getB() {

return  "You can access the test";

}

Will not work:

@Get("/test")

@Access("CAN_ACCESS_TEST")

getB() {

return  "You can access the test";

}

Mullayam/api-starter