kobp

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.

The withDocument() or withDecorator.builder() decorator is tiny middleware that create the document on first run only which relies on Reflect-metadata to pass the data through.

the document will the be available by adding SwaggerController to your routers.

Please see example/simplest for more example.

import type { KobpServiceContext } from 'kobp'
import { Route, BaseRoutedController, withDocument, withValidation } from 'kobp'
// Choose your own validation engine 
import { z } from 'zod'
// Both are parsable by withValidation middleware. 
import { s } from 'ajv-ts'

export class HelloController extends BaseRoutedController {

  @Route({
    method: 'post',
    path: '/echo',
    middlewares: [
      withValidation({
        // Validate header, query, parameters, body with unified schema validation
        query: s.object({
          foo: s.string().describe('Foo!'),
          bar: s.string().describe('Bar!'),
        }),
        // If you don't care about keeping thing simple. You can use zod here, ajv-ts on other object!
        body: z.object({
          message: z.string().describe('Message to say hi to!'),
          data: z.object({
            work: z.number().describe('numeric value describe amount of work you need for this say hi!')
          }),
        })
      }),
      withDocument({ tags: ['hello'], description: 'run migration script' }),
    ])
  async echoFn(context: KobpServiceContext) {
    // These objects are validated!
    const query = context.query
    const body = context.request.body
    // These response body can also be documented! Please see examples/simplest for more info!
    return {
      message: `hi ${query.foo}`,
      body: 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