axiosleo/node-koapp/koapp

@axiosleo/koapp Framework Overview

@axiosleo/koapp is a Node.js framework built on top of Koa that provides three runtime modes (HTTP, TCP, WebSocket) behind a unified Application base, plus batteries-included helpers for routing, validation, response shaping, and Server-Sent Events.

Minimum Node.js version: 16.0.0.

Installation

npm install @axiosleo/koapp

Core Exports

All symbols below come from require('@axiosleo/koapp'):

Full quick-start example lives in quick-start.md.

Class Hierarchy

EventEmitter
  └── Application (src/apps/app.js)
        ├── KoaApplication (src/apps/koa.js) - HTTP
        └── SocketApplication (src/apps/socket.js) - TCP
              └── WebSocketApplication (src/apps/websocket.js) - WebSocket

WebSocketApplication inherits all connection-management helpers (send, close, sendByConnectionId, closeByConnectionId, getConnection, ping, broadcast) from SocketApplication. Only the send, close, and broadcast transport wrappers are overridden.

Scenario Routing (pick the right skill)

When a task falls into one of these areas, prefer the specialized skill for code-level guidance:

• Building an HTTP / TCP / WebSocket server → koapp-apps
• Defining routes, path params, nested routers, validators → koapp-router
• Returning JSON / HTML / custom status responses → koapp-response
• Organizing handlers into classes with shared helpers → koapp-controller
• Validating and serializing structured payloads → koapp-model
• Pushing real-time events to the browser over HTTP → koapp-sse
• Writing koapp code in TypeScript / typing contexts and routers → koapp-typescript

Request Lifecycle (Koa path)

sequenceDiagram
  participant Client
  participant Koa as Koa Middleware Chain
  participant WF as koa.workflow
  participant Handler as Router Handler
  Client->>Koa: HTTP request
  Koa->>Koa: session + body parser
  Koa->>WF: workflow.start(context)
  WF->>WF: resolve route + validate
  WF->>WF: router middlewares
  WF->>Handler: handler(context)
  Handler-->>WF: throw success/failed/result/error
  WF->>WF: router afters
  WF->>Koa: handleRes(context)
  Koa-->>Client: response

The response functions (success, failed, result, response, error) deliberately throw a typed object that the workflow catches and turns into the actual Koa or socket response. Inside handlers, call them and return is implicit - no need to return the result of success(...).

Conventions enforced by the framework

1. Code uses 'use strict', CommonJS, and async/await - follow suit in user

code unless the target project uses TypeScript (see koapp-typescript and the init scaffold under assets/monorepo/apps/services/).

1. Response payloads (JSON) are always wrapped as

{ request_id, timestamp, code, message, data }. code is a "<status>;<message>" string.

1. Path parameters use /{:name} syntax, e.g. /users/{:id}/posts/{:postId}.

Legacy :name is also accepted but {:name} is preferred.

1. A router with method unset (or empty string) is effectively disabled -

requests will resolve to the fallback /*** handler.

1. Validation rules use validatorjs

syntax and live under validators.params|query|body.

When NOT to use koapp directly

• Pure static file serving without API - koa-static alone is lighter
• Heavy enterprise microservices needing opinionated DI / RPC - use NestJS
• Edge-runtime deployments (Cloudflare Workers / Vercel Edge) - the framework

depends on Node-only APIs (net, ws, fs)

Related Resources

• Quick start walkthrough: quick-start.md
• Published on npm: @axiosleo/koapp
• Source: https://github.com/AxiosLeo/node-koapp