DP-Koa Framework Core

0.1.8 verified Mon Apr 27 auth: no javascript

dp-koa-framework-core is a v2 upgrade of the DP-Koa framework core at version 0.1.8, a lightweight, decorator-driven Node.js web framework built on Koa. It enables class-based controllers with decorators for routing (@Get, @Post, @Put, @Del, @All), parameter injection (@Body, @Query, @Params, @State, @Session, @Headers), DTO validation using class-validator, response control (@ResponseCode, @ResponseHeader), HTTP redirects, and an extensible annotation processor system for cross-cutting concerns like logging, authentication, and rate limiting. It supports both legacy and new annotation execution modes switchable via environment variable (USE_NEW_ANNOTATION_SYSTEM=1). Ships TypeScript types. Release cadence is irregular; actively maintained.

Common errors

error Cannot find module 'dp-koa-framework-core' ↓

cause Package not installed or import path is incorrect.

fix

npm install dp-koa-framework-core

error TypeError: bindRouter is not a function ↓

cause Using CommonJS require instead of ESM import.

fix

Change require('dp-koa-framework-core').bindRouter to import { bindRouter } from 'dp-koa-framework-core'.

error Validation failed for DTO: page must be an integer ↓

cause DTO property is string but @Transform was omitted or class-validator not installed.

fix

Add @Transform((v) => Number(v)) and ensure class-validator and class-transformer are installed.

Warnings

breaking v2 uses new annotation system by default? Check environment variable USE_NEW_ANNOTATION_SYSTEM. Old system is default (0). Set to 1 to enable processor-based annotation execution. Some decorators may behave differently. ↓

fix Set process.env.USE_NEW_ANNOTATION_SYSTEM = '1' or call MigrationHelper.initializeNewSystem() if you intend to use processors (Logging, Permission, etc.).

deprecated The old annotation system (default) may be removed in future major versions. Users should migrate to new processor-based system. ↓

fix Enable new system and test all decorators for compatibility. See MigrationHelper.

gotcha DTO validation requires both class-validator and class-transformer as dependencies. They are not shipped with the package; must be installed separately. ↓

fix npm install class-validator class-transformer

gotcha Do NOT mix named and default imports for decorators. All common decorators (Get, Post, etc.) are named exports only. ↓

fix Always use import { Get } from 'dp-koa-framework-core'.

breaking The redirect() function returns a special object, not a plain JSON. Ensure your controller returns redirect(...) directly; do not wrap in another object. ↓

fix Use: return redirect(url, { status: 302 }); not return { data: redirect(...) }.

Install

npm install dp-koa-framework-core

yarn add dp-koa-framework-core

pnpm add dp-koa-framework-core

Imports

Get

wrong

import { Get } from 'dp-koa-framework-core/decorators'

correct

import { Get } from 'dp-koa-framework-core'

Get is exported from the main entry; no subpath import.

bindRouter

wrong

const { bindRouter } = require('dp-koa-framework-core')

correct

import { bindRouter } from 'dp-koa-framework-core'

ESM-only; CommonJS require is unsupported.

bootstrap

wrong

import { bootstrap } from 'dp-koa-framework-core/bootstrap'

correct

import { bootstrap } from 'dp-koa-framework-core'

bootstrap is a named export from the main module.

MigrationHelper
```
import { MigrationHelper } from 'dp-koa-framework-core'
```
Used to programmatically initialize new annotation system.
router
```
import { router } from 'dp-koa-framework-core'
```
An instance of koa-router, configured by bindRouter.

Quickstart

Shows minimal setup: import core decorators and utilities, define a controller with @Get and @Query, bind routes, and start Koa app.

import Koa from 'koa';
import bodyParser from 'koa-bodyparser';
import { bindRouter, router, Get, Query, bootstrap, logger } from 'dp-koa-framework-core';

class HelloController {
  @Get('/hello')
  async hello(@Query() query: any) {
    return { code: 0, data: { message: 'hello', query } };
  }
}

async function main() {
  const app = new Koa();
  app.use(bodyParser());
  bindRouter('', HelloController);
  app.use(router.routes()).use(router.allowedMethods());
  const port = process.env.PORT ? parseInt(process.env.PORT, 10) : 3000;
  app.listen(port, () => logger.info(`listening on :${port}`));
}

main();