kobp
v3.0.9
Published
Koa Boilerplate with MikroORM
Downloads
3,429
Readme
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