ollita7 / kiwi

Built using only nodejs core. Lightweight, intuitive together with great performance and response timing.

Framework to help building a REST API using typescript and node.

Table of Contents

• Installation
• Sample
• Middleware
• Authorization
• Cors
• Prefix
• Dependency Injection
• Sockets
• Documentation

Installation

1. Install module: npm install kiwi-server --save

   npm install kiwi-server-cli -g

   Optional: https://github.com/ollita7/kiwi-cli

2. Add these options to the tsconfig.json file of your project:

   {
       "emitDecoratorMetadata": true,
       "experimentalDecorators": true
   }

Sample

1. Create your first controller class user-controller.ts

   import { Get, Post, Put, JsonController, Param, Body, QueryParam, Authorize, HeaderParam, Delete } from '../../../src/index';
   import { UserModel } from '../../models/models';
   import { isNil } from 'lodash';
   import { Utils } from '../../utils';
   
   @JsonController('/user')
   export class UserController {
       constructor() {}
   
       @Authorize(['Admin'])
       @Post('/create')
       public create(@Body() user: UserModel) {
           user.id = Utils.userList.length + 1;
           Utils.userList.push(user);
           return user;
       }
   
       @Authorize(['Admin'])
       @Get('/get/:id')
       public getById(@Param('id') id: number) {
           var user = Utils.userList.filter(function(obj) {
           return obj.id === id;
           });
   
           return user;
       }
   
       @Authorize(['Admin'])
       @Put('/update')
       public update(@Body() user: UserModel) {
           let userAux = Utils.userList.find(x => x.id == user.id);
           let index = Utils.userList.indexOf(userAux);
           Utils.userList[index] = user;
           return true;
       }
   
       @Authorize(['Admin'])
       @Delete('/delete/:id')
       public delete(@Param('id') id: number) {
           Utils.userList = Utils.userList.filter(function(obj) {
           return obj.id !== id;
           });
           return true;
       }
   }

   We can use QueryParams to get an object with the keys and values that we send on the url.

   For example if you send something like http://.../testcontroller/queryparam/1?name=guille&lastname=fernandez you will receive an object like below:

       @Get('/listFilter')
       public listFilter(@QueryParam() params: any) {
           if (!isNil(params)) {
           var users = Utils.userList.filter(function(obj) {
               return obj.name === params.name && obj.age === +params.age;
           });
           }
           return users;
       }

   {
       "name": "guille",
       "age": 33
   }

   We can use HeaderParams to get http headers. In the next example we are going to receive the token HTTP header if it exists.

   @Get('/search/:name')
   public queryparam(@Param('name') name: string, @HeaderParam('token') token: string) {
       this.aux.print(token);
       if (!isNil(name)) {
       var users = Utils.userList.filter(function(obj) {
           return obj.name === name;
       });
       }
       return users;
   }

2. After creating the controller, create the server that uses that controller.

   import { createKiwiServer } from 'kiwi-server';
   import { UserController } from './controllers/user/user-controller';
   
   const options = {
       controllers: [UserController],
   };
   const server = createKiwiServer(options);
   server.listen(8086);

Middlewares

1. You can create middlewares to execute activities before and after the execution of an action.

   For example to enable CORS we use a specific middleware that is in charge of adding the HTTP headers for that. It's important to execute next if you want the flow to continue executing. Otherwise the flow finishes and you must do something with the response, if you don't the client never gets a response. Below is an example that executes before any action.

   Also you can add the order that you want to execute your middlewares:

   import { IMiddleware } from '../../src/middlewares/middleware';
   import { MiddlewareAfter } from '../../src/decorators/middlewareAfter';
   import * as http from 'http';
   
   @MiddlewareAfter(1)
   export class UserMiddleware implements IMiddleware{
   
       execute(request: http.IncomingMessage, response: http.ServerResponse, next: any){
           response.setHeader( 'Authorization', 'token' );
           console.log('UserMiddleware execute');
           next();
       }
   }

Authorization

1. On the controller specify what actions need to be authorized, using the @Authorize decorator. In the following example we only need to authorize the put action. You can also put the decorator in the controller if all the actions need to be authorized.

   @Get('/list')
   public listAll() {
       return Utils.userList;
   }
   
   @Authorize(['Admin'])
   @Put('/update')
   public update(@Body() user: UserModel) {
       let userAux = Utils.userList.find(x => x.id == user.id);
       let index = Utils.userList.indexOf(userAux);
       Utils.userList[index] = user;
       return true;
   }

2. On the server define the function that is going to be executed everytime an action or a controller has the @Authorize decorator. If that function returns false the service is going to return 401 HTTP error, in other case it will continue the normal execution path.

   import { createKiwiServer } from 'kiwi-server';
   import { UserController } from './controllers/user/user-controller';
   
   async function validateAuthentication(request: http.IncomingMessage, roles: Array<string>): Promise<AuthorizeResponse | boolean> {
       console.log(roles);
       return new AuthorizeResponse(403, 'custom message');
       // return true if want to continue execution
   }
   
   const options = {
       controllers: [UserController],
       authorization: validateAuthentication
   }
   const server = createKiwiServer(options);
   server.listen(8086);

CORS

1. You can enable cross domain by configuration

   import { createKiwiServer } from 'kiwi-server';
   import { UserController } from './controllers/user/user-controller';
   
   const options = {
       controllers: [UserController],
       cors: {
           enabled: true,
           domains: ['domain1.com', 'domain2.com']
       }
   }
   const server = createKiwiServer(options);
   server.listen(8086);

Prefix

1. You can add a prefix for all the URLs. In the following example, all the URLs will have the v1/ prefix:

   import { createKiwiServer } from 'kiwi-server';
   import { UserController } from './controllers/user/user-controller';
   
   const options = {
       controllers: [UserController],
       prefix: 'v1/'
   }
   const server = createKiwiServer(options);
   server.listen(8086);

Context

We can set variable in context to use on methods.

@Post('/test123')
public test23(@Body() body: any, @Context('ctx') my_context: any) {
    return body;
}

Dependency Injection

1. You can use dependency injection in your controllers, by adding arguments to the constructor. Then you can use that in any method that you want.

   import { Get, Post, Put, JsonController, Param, Body, QueryParam, Authorize, HeaderParam, Delete } from '../../../src/index';
   import { UserModel } from '../../models/models';
   import { isNil } from 'lodash';
   import { AuxiliaryFunctions } from '../../auxiliaryFunctions';
   
   @JsonController('/user')
   export class UserController {
       constructor(private aux: AuxiliaryFunctions) {}
   
       @Get('/search/:name')
       public queryparam(@Param('name') name: string, @HeaderParam('token') token: string) {
           this.aux.print(token);
           if (!isNil(name)) {
           var users = Utils.userList.filter(function(obj) {
               return obj.name === name;
           });
           }
           return users;
       }
   }

Sockets

1. socket.io is integrated to our framework. Enable socket support by adding the socket property to the options.

   const options = {
       controllers: [UserController],
       documentation: {
           enabled: true,
           path: '/apidoc'
       },
       socket: true
   }
   
   const server = createKiwiServer(options, socketInit);
   
   function socketInit() {
       const io = getSocket();
       io.on('connection', (socket: any) => {
           socket.userId  = socket.handshake.query.user;
       });
   }

   Finally use getSocket in any place of the application and start using it.

Documentation

1. Enable automatic swagger documentation, setting the path where it will be accessible.

   import { createKiwiServer } from 'kiwi-server';
   import { UserController } from '../controllers/user/user-controller';
   
   const options = {
       controllers: [UserController],
       prefix: 'v1/',
       cors: true,
       documentation: {
           enabled: true,
           path: '/apidoc'
       }
   }
   const server = createKiwiServer(options);
   server.listen(8086);

2. Decorate your models

   import { IsString, IsNumber, IsArray } from '../../src/index'
   
   export class AddressModel {
       @IsString() public street: string;
       @IsNumber() public number: number;
   }
   
   export class UserModel {
       @IsNumber() public id: number;
       @IsString()  public name: string;
       @IsString()  public lastname: string;
       @IsNumber() public age: number;
       @IsArray(() => AddressModel) public address: AddressModel[];
   }

3. Visit the documentation page, in this example it would be at http://localhost:8086/v1/apidoc

kiwi's Issues

Optional prefix to the server

If you don't specify a prefix the server starts but doesn't receive the requests.

Another detail, in the "prefix" section of the README.md file indicates:

const options = {
    controllers: [UserController],
    **prefix: 'v1/'** // _I had to change to prefix: '/v1' to do it works_
}

The framework is awesome!
Thanks!

Swagger: array types are not included in the documentation

When a type contains a typed-array, it isn't included in the documentation:

export class TimesheetEntry {
  @IsInt() projectId: number;
  @IsDate() date: Date;
  @IsInt() hours?: number;
}

export class TimesheetEntries {
  @IsArray() entries: TimesheetEntry[];
}

Api documentation group

I need to group the methods in the API documentation, grouped by controllers path.
Thanks!

Copy all sources when build

It would be great if all sources in "src" folder are copied to "dist" folder when build with "kc build".
In my case, I have developed another JS modules in node with the business logic.
Thanks!

Add support for @Authorize at class level

Right now the @authorize is only available for properties. It will be good to have at class level.

Add dockerfile

It would be great if you can share a dockerfile suggested for docker configuration.
I think this could be very useful.
Thanks in advance!

Swagger Does not pull schema definitions for routes.

Documentation on the Docs module is kind of sparse to begin with. Is there a way that we could use a decorator to mark a class as a schema for swagger? I'm a little new to contributing, but I've been using Kiwi for several months now. If you show me the files to modify, and maybe how you're picking up schemas now, I can try to implement and PR this.

Setting http status code in controller

Is there a way to set the status code in the controller?

Cross domain doesnt work with angular

It is throwing error when angular makes OPTION request.

Api doc

Api doc path doesn't include prefix

Swagger documentation not working for object arrays

E.g.:
[{ id: 1, name: "Test" }, { id: 2, name: "Test 2" }]

This only happens when the body is an array itself:

  @Post('/')
  public async add(@Body() timesheet: TimesheetEntry[], req: IncomingMessage) {
    try {
        ...

validateAuthentication - service.ts

I need to get the header data to be able to validate them.

Swagger: documentation resources depend on the path where it is executed