web_api_base 2.7.3 → 3.2.1

package/readme.md

@@ -2,7 +2,7 @@
 
 web_api_base is a npm packaged that allows to create web-apis like MVC of .NET
 
-## Installation
+# Installation
 
 
 
@@ -11,7 +11,7 @@ npm install web_api_base
 ```
 
 
-## Usage
+# Usage
 
 First of all we need implement the abstract class __Application__. 
 After that, we need to create some controllers and they must inherit  the abstract class __ControllerBase__.
@@ -26,14 +26,14 @@ npx create-controller
 
 ```typescript
 
-import { ControllerBase, Route, Action } from "web_api_base";
+import { ControllerBase, Route, GET } from "web_api_base";
 
 
 @Route()
 export default class SampleController extends ControllerBase
 {   
      
-    @Action()
+    @GET()
     public Hello() : void
     {
         this.OK({message: "Hello Word!"})
@@ -78,7 +78,7 @@ import Application from './Application';
 new Application().StartAsync();
 ```
 
-## Dependecy Injection
+# Dependecy Injection
 Consider this abstraction of a service and some imnplementations
 
 ### ./services/SampleService.ts
@@ -110,7 +110,7 @@ We can use the DI service like this
 
 ```typescript
 
-import { ControllerBase, Route, Action, Inject } from "web_api_base";
+import { ControllerBase, Route, GET, Inject } from "web_api_base";
 import {SampleServiceAbstract } from '../services/SampleService.ts';
 
 @Route()
@@ -125,7 +125,7 @@ export default class SampleController extends ControllerBase
         this.SomeDepency = someDependecy ;        
     }
      
-    @Action()
+    @GET()
     public Hello() : void
     {
         this.OK({message: "Hello Word!"})
@@ -166,6 +166,222 @@ export default class App extends Application
 
 ```
 
+
+# HTTP Verbs decorators
+
+### @GET()
+Create a GET endpoint 
+
+### @PUT()
+Create a PUT endpoint 
+
+### @POST()
+Create a POST endpoint 
+
+### @DELETE()
+Create a DELETE endpoint 
+
+
+# Model Bind decorators
+
+### @FromBody()
+Extract a method parameter type instance from body of request
+
+```json
+{
+"Name": "Adriano Marino Balera",
+"Email": "adriano@gmail.com",
+"Age" : 30
+}
+```
+
+```typescript
+ @POST()
+ public async Insert(@FromBody()user : User) : Promise<void>
+ {  
+     this.OK(await this._service.AddAsync(user));
+ }
+```
+In the example above, the __model binding system__ will cast the body in a intance of type __User__.
+
+We can extract some part of body using named FromBody args: __@FromBody('user')__. The __model binding system__ will use the 'user' property of body json. 
+
+```json
+{
+  "user" : 
+  {
+        "Name": "Adriano Marino Balera",
+        "Email": "adriano@gmail.com",
+        "Age" : 30
+  }
+}
+```
+### @FromQuery()
+Extract the method parameter from query string of request
+
+```typescript
+@GET()    
+public async GetById(@FromQuery()id : number) : Promise<void>
+{ 
+     this.OK(await this._service.GetByIdAsync(id));
+}     
+```
+In the example above, the __model binding system__ will get the first query argument of request. 
+We can also determine the name of parameter: __@FromQuery('id')__. 
+
+
+
+## Sample of a complete controller
+
+```typescript 
+
+import { ControllerBase, Route, POST, PUT, DELETE, GET, Inject, Validate, FromBody, FromQuery } from "web_api_base";
+import AbstractUserService from "../core/abstractions/AbstractUserService";
+import User from "../core/entities/User";
+
+@Validate()
+@Route('/v1/users/')
+export default class UserController extends ControllerBase
+{   
+    @Inject()
+    private _service : AbstractUserService;
+
+    constructor(service : AbstractUserService)
+    {
+        super();                    
+        this._service = service;
+    }
+    
+    @GET("list")
+    public async GetAll() : Promise<void>
+    {       
+        this.OK(await this._service.GetAllAsync());
+    }
+    
+    @GET("permissions")
+    public async GetAllPermissions() : Promise<void>
+    {       
+        this.OK(await this._service.GetAllPermissions());
+    }
+
+    @GET()    
+    public async GetById(@FromQuery("id")id : number) : Promise<void>
+    { 
+       this.OK(await this._service.GetByIdAsync(id));
+    }          
+    
+    @POST()
+    public async Insert(@FromBody()user : User) : Promise<void>
+    {  
+        this.OK(await this._service.AddAsync(user));
+    }
+    
+    @PUT()   
+    public async Update(@FromBody()user : User, ) : Promise<void>
+    {        
+        if(user.Id == undefined || user.Id <= 0)
+            return this.BadRequest({ Message : "The ID must be greater than 0"});
+
+        this.OK(await this._service.UpdateAsync(user));
+    }
+
+    @DELETE()    
+    public async Delete(@FromQuery()id : number) : Promise<void>
+    {  
+        let del = await this._service.GetByIdAsync(id);
+
+        if(!del)
+            return this.NotFound();
+
+        this.OK(await this._service.DeleteAsync(del));
+    }
+}
+
+```
+
+
+# Validation decorators
+
+### @Validate() 
+Say that all arguments from model bind will be validated before injected on the controller action. 
+This decorator must be used in the controller declaration.
+```typescript
+@Validate()
+@Route('v1/users/')
+export default class UserController extends ControllerBase
+```
+
+### @Required()
+Determine whether a property of a class is required
+
+### @Max(max : number)
+Determine the maximun value of a number property
+
+### @Min(min: number)
+Determine the minimun value of a number property
+
+### @MaxLenght(max : number)
+Determine the maximun number of characters of a string
+
+### @MaxLenght(min : number)
+Determine the minumun number of characters of a string
+
+### @Regex(exp : RegExp)
+Determine is a string field match determined pattern 
+
+### @Rule<T>(action : (arg : T) => boolean)
+Check whether some property respect some validation rule
+
+
+### Sample of a complete object
+
+```typescript
+
+import {Required, MaxLenght, MinLenght, Rule, Max, Min, Regex}  from 'web_api_base';
+
+
+export default class ValidatedObject
+{
+    @Max(10)
+    public MaxValue : number;
+
+    @Min(10)
+    public MinValue : number;
+
+    @Min(10)
+    @Max(20)
+    public Range: number;
+
+    @Regex(/^[^\s@]+@[^\s@]+\.[^\s@]+$/)
+    public RegExp : string;
+
+    @Required()    
+    public Required : string;
+
+    @MaxLenght(20)    
+    public MaxLenght : string;
+
+    @MinLenght(10)
+    public MinLenght : string;
+    
+    @Rule<string[]>(p => p.length > 5)    
+    public Permissions : string[];
+
+    constructor()
+    {
+        this.MaxValue = -1;
+        this.MinValue = -1;
+        this.Range = -1;
+        this.Required = "";
+        this.MaxLenght = ""; 
+        this.MinLenght = ""; 
+        this.RegExp = "";
+        this.Permissions = [];
+    }
+}
+```
+
+
 ## Contributing
 
 Pull requests are welcome. For major changes, please open an issue first