Koa-smart NPM | npm.io

KoaSmart is a framework based on Koajs2, which allows you to develop RESTful APIs with : Class, Decorator, Params checker

A framework based on Koajs2 with Decorator, Params checker and a base of modules (cors, bodyparser, compress, I18n, etc... ) to allow you to develop a smart api easily

  export default class RouteUsers extends Route {

    // get route: http://localhost:3000/users/get/:id
    @Route.Get({
      path: 'get/:id'
    })
    async get(ctx) {
      const user = await this.models.users.findById(ctx.params.id);
      this.assert(user, 404, 'User not found');
      this.sendOk(ctx, user);
    }

    // post route: http://localhost:3000/users/add
    @Route.Post({
      accesses: [Route.accesses.public],
      bodyType: Types.object().keys({
        email: Types.string().required(), // return an 400 if the body doesn't contain email key
        name: Types.string().uppercase(), // optional parameter
      }),
    })
    async add(ctx) {
      const body = this.body(ctx); // or ctx.request.body
      // body can contain only an object with email and name field
      const user = await this.models.user.create(body);
      this.sendCreated(ctx, user);
    }

  }

Api documentation

Summary

What is in this framework ?

This framework gives you the tools to use a set of modules:

For routing
- koajs 2 as the main, underlying framework
- kcors is used to handle cross-domain requests
- koa2-ratelimit To limit bruteforce requests
- koa-helmet helps you secure your api
- koa-body to parse request bodies
- koa-compress to compress the response
- koa-i18n for Internationalization (I18n)
moment Parse, validate, manipulate, and display dates in javascript.
jsonwebtoken an implementation of JSON Web Tokens JWT
💪 @Decorators to ensure a better project structure
🚀 Automatic doc generation
👀 Grants Access

Install

npm install --save koa-smart Or use the boilerplate (koa-smart-boilerplate)

Router with decorator

All routes have to extend the Route class in order to be mount

Prefix of routes
If you have a route class with the name RouteMyApi, all the routes inside said class will be preceded by /my-api/
- How does it work ?
  1. the Route word is removed
  2. uppercase letters are replaced with '-'. (essentially converting camelCase into camel-case) e.g.: this will add a get route => http://localhost:3000/my-api/hello
```
export default class RouteMyApi extends Route {

    @Route.Get({})
    async hello(ctx) {
        this.sendOk(ctx, 'hello');
    }

}
```
- Change prefix of all routes in the class: http://localhost:3000/my-prefix/hello
```
@Route.Route({
    routeBase: 'my-prefix',
})
export default class RouteMyApi extends Route {

    @Route.Get({})
    async hello(ctx) {
        this.sendOk(ctx, 'hello');
    }

}
```

Get route http://localhost:3000/my-api/hello

  @Route.Get({})
  async hello(ctx) {
    this.sendOk(ctx, null, 'hello');
  }

Change path http://localhost:3000/my-api/myroute/15

  @Route.Get({
    path: '/myroute/:id'
  })
  async hello(ctx) {
    this.sendOk(ctx, 'hello' + ctx.params.id);
  }

Post route http://localhost:3000/my-api/user-post

  @Route.Post({
    bodyType: Types.object().keys({ // body to allow: all other params will be rejected
      email: Types.string().required(), // return an 400 if the body doesn't contain email key
      name: Types.string().uppercase(), // optional parameter
    }),
  })
  async userPost(ctx) {
    const body = this.body(ctx);
    // body can contain only an object with email and name field
    const user = await this.models.user.create(body);
    this.sendCreated(ctx, user);
  }

Disable route

Disable all routes in a class

to disable all routes in a class you should add disable in the content of your decorator class

@Route.Route({
    disable: true,
})
export default class RouteMyApi extends Route {
    // All routes in this class will not be mounted
}

Disable a specific route

to disable a specific route you can add disable in the content of your decorator

@Route.Get({
    disable: true, // this route will not be mounted
})
async hello(ctx) {
  this.sendOk(ctx, null, 'hello');
}

Grant accesses

Koa smart allows grant permission to be handled in a simple and efficient manner.

Each function passed to accessers will be given the koa context (ctx) as a parameter, and must return a boolean to express whether is grants access to the route or not.

If at least one of the function given returns true, access to the route will be granted.

  async function isConnected(ctx) {
    // TODO test if the user is connected
    return ctx.state.user;
  }
  async function isUserPremium(ctx) {
    // TODO test if the user is premium
    return ctx.state.user.isPremium;
  }
  async function isAdmin(ctx) {
    // TODO test if the user is a admin
    return ctx.state.user.isAdmin;
  }

Of a Class

@Route.Route({ accesses: [isConnected] })
class RouteMiddlewares extends Route {
  @Route.Get({})
  async view(ctx, next) {
    console.log('I can be call if the current client is connected');
    this.sendOk(ctx, null, 'OK');
  }
}

Of a specific route

@Route.Get({})
async myPublicRoute(ctx, next) {
  console.log('I am a public route, I can be call by any one');
  this.sendOk(ctx, null, 'OK');
}

@Route.Get({ accesses: [isConnected] })
async myConnectedRoute(ctx, next) {
  console.log('I can be call if the current client is connected');
  this.sendOk(ctx, null, 'OK');
}

@Route.Get({ accesses: [isUserPremium, isAdmin] })
async myPremiumRoute(ctx, next) {
  console.log('I can be call if the current client is connected and premium or admin');
  this.sendOk(ctx, null, 'OK');
}

RateLimit : For more infos, see the koa2-ratelimit module

Configure

import { App } from 'koa-smart';
import { RateLimit, RateLimitStores } from 'koa-smart/middlewares';

const app = new App({ port: 3000 });

// Set Default Option
const store = new RateLimitStores.Memory() OR new RateLimitStores.Sequelize(sequelizeInstance)
RateLimit.defaultOptions({
    message: 'Too many requests, get out!',
    store: store, // By default it will create MemoryStore
});

// limit 100 accesses per min on your API
app.addMiddlewares([
  // ...
  RateLimit.middleware({ interval: { min: 1 }, max: 100 }),
  // ...
]);

RateLimit On Decorator

Single RateLimit

@Route.Get({ // allow only 100 requests per day to /view
    rateLimit: { interval: { day: 1 }, max: 100 },
})
async view(ctx) {
  this.sendOk(ctx, null, 'hello');
}

Multiple RateLimit

// Multiple RateLimit
@Route.Get({
    rateLimit: [
        { interval: { day: 1 }, max: 100 }, // allow only 100 requests per day
        { interval: { min: 2 }, max: 40 }, // allow only 40 requests in 2 minutes
    ],
})
async hello(ctx) {
  this.sendOk(ctx, null, 'hello');
}

Middlewares

Of a Class

@Route.Route({
    middlewares: [ // Array of middlewares
      async (ctx, next) => {
        console.log('I will be call before all route in this class');
        await next();
      },
    ],
})
class RouteMiddlewares extends Route {
    @Route.Get({})
    async view(ctx, next) {
      console.log('I will be call after middlewares of class');
      this.sendOk(ctx, null, 'hello');
    }
}

Of a specific route

@Route.Get({
    middlewares: [ // Array of middlewares
      async (ctx, next) => {
        console.log('I will be call before the route but after middlewares of class');
        await next();
      },
    ],
})
async view(ctx, next) {
    console.log('I will be call after middlewares of the class and route');
    this.sendOk(ctx, null, 'hello');
}

Params checker: See the doc of Types for more information

`bodyType` to check body params

quick example

  @Route.Post({ // or Put, Patch
    bodyType: Types.object().keys({
      email: Types.string().regex(/\S+@\S+\.\S+/).required(),
      password: Types.string().min(8).required(),
      address: Types.object().keys({
        country: Types.string().required(),
        street: Types.string().required(),
      }).required(),
    }),
  })
  async user(ctx) {
    // this is the body manage by bodyType
    const bodyParams = this.body(ctx);

    // this is the origin body pass
    const originBodyParams = this.body(ctx, true);
  }

`queryType` to check query params

quick example

  @Route.Get({
    queryType: Types.object().keys({
      limit: Types.number().integer().required().default(10),
      offset: Types.number().integer().required().default(10),
    }),
  })
  async users(ctx) {
    // this can contain only limit and offset
    const queryParams = this.queryParam(ctx);

    // this is the origin queryParams pass
    const originQueryParams = this.queryParam(ctx, true);
  }

Automatic documention generation: See the manual for more information

Get Started (quick-start boilerplate)

in order to get started quickly, look at this boilerplate, or follow the instructions below:

import the app and your middlewares

import { join } from 'path';
// import the app
import { App } from 'koa-smart';
// import middlewares koa-smart give you OR others
import {
  bodyParser,
  compress,
  cors,
  handleError,
  RateLimit,
  ...
} from 'koa-smart/middlewares';

create an app listening on port 3000

const myApp = new App({
  port: 3000,
});

add your middlewares

myApp.addMiddlewares([
  cors({ credentials: true }),
  helmet(),
  bodyParser({ multipart: true }),
  handleError(),
  RateLimit.middleware({ interval: { min: 1 }, max: 100 }),
  ...
]);

add your routes mount a folder with a prefix (all file who extends from Route will be added and mounted)
```
    myApp.mountFolder(join(__dirname, 'routes'), '/');
```
Start your app
```
myApp.start();
```

Full example

Basic one

import { join } from 'path';
// import the app
import { App } from 'koa-smart';
// import middlewares koa-smart give you OR others
import {
  i18n,
  bodyParser,
  compress,
  cors,
  helmet,
  addDefaultBody,
  handleError,
  logger,
  RateLimit,
} from 'koa-smart/middlewares';

const myApp = new App({
  port: 3000,
});

myApp.addMiddlewares([
  cors({ credentials: true }),
  helmet(),
  bodyParser({ multipart: true }),
  i18n(myApp.app, {
    directory: join(__dirname, 'locales'),
    locales: ['en', 'fr'],
    modes: ['query', 'subdomain', 'cookie', 'header', 'tld'],
  }),
  handleError(),
  logger(),
  addDefaultBody(),
  compress({}),
  RateLimit.middleware({ interval: { min: 1 }, max: 100 }),
]);

// mount a folder with an prefix (all file who extends from `Route` will be add and mount)
myApp.mountFolder(join(__dirname, 'routes'), '/');

// start the app
myApp.start();

Other example who Extends class App

import { join } from 'path';
// import the app
import { App } from 'koa-smart';
// import middlewares koa-smart give you OR others
import {
  i18n,
  bodyParser,
  compress,
  cors,
  helmet,
  addDefaultBody,
  handleError,
  logger,
  RateLimit,
} from 'koa-smart/middlewares';

// create an class who extends from App class
export default class MyApp extends App {
  constructor() {
    super({ port: 3000 });
  }

  async start() {
    // add your Middlewares
    super.addMiddlewares([
      cors({ credentials: true }),
      helmet(),
      bodyParser({ multipart: true }),
      i18n(this.app, {
        directory: join(__dirname, 'locales'),
        locales: ['en', 'fr'],
        modes: ['query', 'subdomain', 'cookie', 'header', 'tld'],
      }),
      handleError(),
      logger(),
      addDefaultBody(),
      compress({}),
      RateLimit.middleware({ interval: { min: 1 }, max: 100 }),
    ]);

    // mount a folder with an prefix (all file who extends from `Route` will be add and mount)
    super.mountFolder(join(__dirname, 'routes'));
    return super.start();
  }
}

// start the app
const myApp = new MyApp();
myApp.start();

Upgrade to 4.0.0

4.0.0 upgrades koa2-ratelimit to version 1.0.0

This means koa2-ratelimit does not install sequelize, mongoose or redis anymore. If you use these packages, make sure you install them in your project.