AlionJS – tiny TCP-first Node.js web framework

AlionJS is a zero-dependency experimental framework that sits on top of Node’s net module. It teaches how HTTP works under the hood by exposing every layer: sockets, parsing, routing and responses. Use it for learning, rapid prototyping, or embedding a micro HTTP server without pulling the entire http stack.

Why AlionJS?

• Socket-level access – built on raw TCP so you fully control the lifecycle.
• Deterministic request parsing – custom parser that extracts method, pathname, query, headers, JSON body and params.
• Composable router – register routes with get/post/put/patch/delete, merge routers and extract dynamic params (/users/:id).
• Chainable responses – ergonomic API (res.status().setHeader().json()) that writes RFC-compliant responses.
• Tiny footprint – ships as TypeScript, compiled to CommonJS, depends only on reflect-metadata.
• Framework-friendly – export surface (AlionServer, Router, AlionResponse, RequestParser) lets you mix and match pieces.

Installation

npm install alionjs
# or
yarn add alionjs

Build TypeScript sources before publishing or when modifying the framework:

npm run build

Quick start

Create a server, register a few routes and start listening on a TCP port.

import { AlionServer, Router } from 'alionjs'

function bootstrap () {
  const server = new AlionServer()
  const router = new Router()

  router.get('/health', (req, res) => {
    res.json({ status: 'ok', timestamp: Date.now() })
  })

  router.get('/users/:id', (req, res) => {
    const { id } = req.params
    res.json({ id, note: 'Params are decoded for you' })
  })

  router.post('/echo', (req, res) => {
    res.status(201).json({ received: req.body, headers: req.headers })
  })

  server.useRouter(router)
  server.listen(8080)
}

bootstrap()

Start the script and hit http://localhost:8080/health. AlionJS logs:

Congratulation Alion Server Running: http://localhost:8080

Core concepts

1. AlionServer

• Wraps a raw net.Server.
• Accepts sockets, parses inbound bytes into AlionRequest.
• Delegates to the router, instantiates AlionResponse, writes back to the same socket.
• Methods:
  • Router() – returns the internal router for direct registration.
  • useRouter(router) – merge multiple routers (micro-modules or feature routers).
  • listen(port, host?, callback?) – starts the TCP server and executes an optional ready callback.

2. Router

• Stores RouteDefinition { method, path, handler }.
• Helpers for the five common HTTP verbs.
• findRoute(request) compares method + pathname, runs ParamsExtractor and augments req.params.
• merge(routes) makes it easy to provide routers from other packages or files.

3. RequestParser

• Splits raw payload into header + body.
• Parses method/path/protocol, lowers headers, decodes query string.
• Detects JSON payloads via content-type and parses body safely.
• Always returns an AlionRequest with defaulted params so handlers work uniformly.

4. AlionResponse

• Stores headers, status code and body until sendResponse() flushes everything.
• .status(code) and .setHeader(key, value) are chainable.
• .send(data) auto-detects JSON payloads; .json(data) enforces JSON.
• Calculates Content-Length and closes the socket to finish the HTTP exchange.

Project structure

src/
  core/
    http.parser.ts      # converts raw TCP payload into AlionRequest
    params.extractor.ts # pulls :params from route patterns
    response.ts         # chainable HTTP response builder
    router.ts           # in-memory router with verb helpers
    server.ts           # TCP server wiring everything together
  index.ts              # public API surface
dist/                   # compiled CommonJS artifacts

Advanced usage

• Multiple routers – build feature routers (authRouter, userRouter) and merge them with server.useRouter.
• Custom transports – reuse Router and AlionResponse in other TCP contexts (UNIX sockets, workers).
• Manual request handling – import RequestParser directly if you need to inspect raw HTTP payloads before routing.
• Streaming / SSE – extend AlionResponse to keep sockets open and push chunks manually.

Debugging tips

• Log the raw chunk received in net.createServer to inspect malformed requests.
• Validate headers before parsing JSON to avoid throwing on invalid payloads.
• When debugging param matching, inspect ParamsExtractor(pattern, actual) directly with sample inputs.
• Use tools like nc, curl --raw or telnet to craft custom HTTP payloads and stress test the parser.

Roadmap ideas

• Middleware stack (before/after hooks).
• Built-in static file server.
• Streaming body parser for large payloads.
• Type-safe route definitions and handler context.
• CLI generator for scaffolding routers.

Contributions and experiments are very welcome—AlionJS is intentionally small so it can be torn apart, rebuilt, and used to learn the guts of HTTP servers.