// create CRUD generic controller on the fly
@genericController(c => {
  // authorize post, put, patch, delete
  c.mutators().authorize("Supervisor", "Staff");
})
// use TypeORM entity as generic controller model
@Entity()
export class Item {
  @PrimaryGeneratedColumn()
  id: number;

  // validate max characters allowed
  @val.length({ max: 128 })
  @Column()
  name: string;

  // authorize request/response body property
  @authorize.readWrite("Supervisor", "Staff")
  @Column()
  basePrice: number;

  // authorize request body property
  @authorize.write("Supervisor")
  @Column()
  price: number;
}

Feature

First Class Entity

Upgrade ORM entity into First Class Entity to have more control to most framework features such as request/response body schema, authorization, validation, generated routes.

In the background, Plumier creates CRUD Restful generic controller uses ORM entity as its data model, example produces:

POST /items accessible by Supervisor and Staff
GET /items?offset&limit&filter&select accessible by any login user
GET /items/{id} accessible by any login user
POST /items/{id} accessible by Supervisor and Staff
PUT /items/{id} accessible by Supervisor and Staff
DELETE /items/{id} accessible by Supervisor and Staff

Learn more about this feature

// register with authorization policy builder
authPolicy()

  // register role
  .register("Supervisor", ({ user }) => {
      // "user" is JWT claim from request header
      // return true to authorize otherwise false
      // also possible to return Promise<boolean>
      return user?.role === "Supervisor"
  })

  // chain-able registration method
  .register("Staff", ({ user }) => {
      return user?.role === "Staff"
  })

Feature

Policy Based Authorization

Plumier supported securing API with JWT out of the box. Plumier also provided authorization to restrict user access based on specific logic defined by you. You define your authorization logic in separate location, then apply it using decorators.

In the background Plumier validates your authorization policy to prevent mistyped policy name, or possibly duplicate/conflict policy name.

Learn more about this feature

@Entity()
export class Post {
  @PrimaryGeneratedColumn()
  id: number

  // turn one to many relation into nested API
  @genericController()
  @OneToMany(x => Comment, x => x.post)
  comments: Comment[]
}

@Entity()
export class Comment {
  @PrimaryGeneratedColumn()
  id: number

  @Column()
  comment:string
}

Feature

Nested First Class Entity

Turn One-To-Many relation of ORM entity into nested Restful API. Nested first class entity best used for Parent - Children specific operation. For example narrowing result based on Parent ID, or restrict access to data based on Parent ID.

POST /posts/{pid}/comments
GET /posts/{pid}/comments?offset&limit&filter&select
GET /posts/{pid}/comments/{id}
POST /posts/{pid}/comments/{id}
PUT /posts/{pid}/comments/{id}
DELETE /posts/{pid}/comments/{id}

Learn more about this feature

export class UsersController {
  readonly repo = new TypeORMRepository(User)

  // GET /users/:id
  @route.get(":id")
  get(id:string) { 

      // return value or Promise 
      // automatically rendered into JSON response
      return this.repo.findOne(id)
  }

  // POST /users
  @route.post("")
  // data parameter bound to request body
  save(data:User) {
    return this.repo.insert(data)
  }
}

Feature

Controllers

Require more flexible response result then using First Class Entity? No problem, you still can use controller to handle user request.

Plumier controller inspired by ASP.Net MVC controllers, and take important role in Plumier system.

Routes generated based on controller name and action name.
Parameter binding using parameter name or decorators.
Extra data type conversion with simple sanitation for each controller parameter.
Policy based authorization that applicable using decorators.

Learn more about this feature

Feature

Swagger UI with Open API v3

Open API v3 schema automatically generated from controller metadata. Mostly no configuration required, but some minor tweak can be applied to get result match your need.

Learn more about this feature

Feature

Performance is Top Priority

Plumier shipped with efficient routing and validator and type converter library. Check the full stack benchmark of performance comparison between Koa, Express, Nest, Loopback 4 on this repository, which tests basic framework functionality: routing, body parser, validation and type conversion