Kobp

Start your Koa project with necessary Boring codes.

Install

npm i --save kobp

# OR

yarn kobp

NOTE we listed koa as our peerDependencies so please include the koa in your own codebase.

Usage

Start your node.js TypeScript project and describe your endpoints with controller style.

To expose each method as routes. Use our built-in decorator. Route which accepts method, paths, and Koa's middlwares.

controllers/hello.cotnroller.ts

import type { KobpServiceContext } from 'kobp'
import { Route, BaseRoutedController } from 'kobp'

export class HelloController extends BaseRoutedController {

  @Route('post', '/echo')
  async migrate(context: KobpServiceContext) {
    return context.request.body
  }

  @Route()
  async index(context: KobpServiceContext) {
    return {
      hello: 'world'
    }
  }
}

Or you can describe your controllers in a classical way. (Avoid using decorators). This method introduce less code when it is bundled.

controllers/hello.controller.ts

import type { KobpServiceContext } from 'kobp'
import { RouteMap, BaseRoutedController } from 'kobp'

export class HelloController extends BasedRouteController {

  public getRouteMaps(): RouteMap {
    return {
      ...super.getRouteMaps(),
      index: { method: 'get', path: '/', middlewares: [] }, // Same as our decorator above.
    }
  }

  async index(context: KobpServiceContext) {
    return {
      hello: 'world'
    }
  }
}

Now to utilise this controller. Here is how we start a module.

// routes.ts
import { KobpServiceContext, KobpServiceState } from 'kobp'

import Router from 'koa-router'
import { HelloController } from 'src/controller/HelloController'

export const makeRoutes = (): Router => {
  const api = new Router<KobpServiceState, KobpServiceContext>()
  api.use('/hello', ...new HelloController().getMiddlewares() as any)
  return api
}

And also ...

// server.ts
import {
  BootstrapLoader,
  BootstrapModule,
} from 'kobp'
import { makeRoutes } from "./routes"

// Finally
const run = async () => {
  const loader = new BootstrapLoader()
  const app = await loader
    .addModule(new BootstrapModule(['json'])) // type of input body it should support.
    .build(makeRoutes(), {}) // returns Koa App
  
  app.listen(9005, '0.0.0.0')
}

run()

By the example above. You will be able to:

curl http://localhost:9005/hello/

# OR

curl -XPOST http://localhost:9005/hello/echo -H 'content-type: application/json' -d '{"some":"key","json":"value"}'

See other Example for more info.

Using with Lambda

import {
  BootstrapModule,
  KobpRouter,
} from 'kobp'

import { makeLambdaHandler } from 'kobp-lambda'
import { HelloController } from '@controllers/hello.controller'

const router = new KobpRouter()
new HelloController().register('/hello', router)

export default makeLambdaHandler(router, {
  customizer: (loader) => {
    loader.addModule(new BootstrapModule(['json']))
  },
  binary: true, // Enable return as binary!
})

Using Swagger

Make sure you have this only dependencies

npm install openapi3-ts

Here is the example to use it.

import type { KobpServiceContext } from 'kobp'
import { Route, BaseRoutedController } from 'kobp'

export class HelloController extends BaseRoutedController {

  @Route('post', '/echo', withDocument({ tags: ['hello'], description: 'run migration script' }))
  async migrate(context: KobpServiceContext) {
    return context.request.body
  }

  @Route()
  async index(context: KobpServiceContext) {
    return {
      hello: 'world'
    }
  }
}

Note that most of the time AWS's Lambda doesn't support return the Response with Binary content. To make it so please make sure you enabled binary mode as per example above.

Enabled Debug Mode

Sometime we need to understand what's going on under the hood of our custom made feature such as RequestContext. Attach the message logging by declare

ENV: KOBP_DEBUG to Yes or True or 1 to let the framework emit debugging messages.

TODO

[/] Example repo
[/] Modularized
[/] Core module
[/] Mikroorm module
[/] Publish with microbundle instead.
[/] Lambda Handler
[/] Swagger Support
[ ] SNS/SQS Handler