@panmdaa/server

Zero-dependency TypeScript HTTP and WebSocket server with a compiled-radix router — no runtime dependencies.

@panmdaa/server is a from-scratch server library built on Node's native http/https/http2 transport. It ships a radix-tree router with three-tier matching (O(1) static map → one compiled regex per method → conflict-safe trie), a code-generated middleware pipeline with conditional await, and a zero-allocation, zero-copy WebSocket stack with permessage-deflate.

npm install @panmdaa/server

Quick look

import {
  Server, Router, cors, securityHeaders, NotFound,
} from "@panmdaa/server";

// Compose routers, mount them on a server
const users = new Router();
users.get("/:id", ({ params, response }) => {
  response.json({ user: params.id });
});

const server = new Server();
server.use(cors({ allowOrigin: "*" }));
server.use(securityHeaders());
server.router("/api/users", users);

// Static route, typed params, lazy response
server.get("/message/:name", ({ params, response }) => {
  response.type("text/html");
  response.send(`Hello, ${params.name}!`);
});

// Typed errors → mapped responses
server.get("/teapot", () => {
  throw new NotFound();
});

// WebSocket route — separate tree, path-only matching
server.ws("/live", ({ socket }) => {
  socket.send("welcome!");
  socket.on("message", ({ data }) => socket.send(`echo: ${data}`));
});

server.listen(3000);

Single entry point: everything — Server, Router, middleware, errors, WebSocket helpers — is exported from @panmdaa/server. See Development.

Routing

Verbs, params, wildcards and composition — all type-checked at compile time:

import { Server } from "@panmdaa/server";

const server = new Server();

// Static, param and wildcard routes
server.get("/", ({ response }) => response.send("index"));
server.get("/user/:id", ({ params, response }) => {
  response.json({ id: params.id });   // params.id: string — typed by the path
});
server.get("/user/:id?/books", ({ params, response }) => { … }); // optional segment
server.get("/static/*", ({ params, response }) => {
  response.json({ file: params["*"] }); // everything after /static/
});

// Body-capable "read" routes (POST, PUT, PATCH, DELETE, QUERY)
server.post("/api/items", async ({ body, response }) => {
  const item = await body.json();
  response.status = 201;
  response.json({ created: item });
});

// Group a prefix in place, or mount an existing router
server.group("/api", (api) => {
  api.get("/health", ({ response }) => response.send("ok"));
});

The matching engine is a three-tier radix tree:

| Tier | What | Cost | |------|------|------| | Static map | routes without params/wildcards | O(1), zero allocation | | Compiled regex | one RegExp per method for dynamic routes | single native exec() | | Trie fallback | only when routes conflict | preserves registration precedence |

Optional segments are expanded into concrete routes at registration; matching never sees a ?. See the router docs.

Middleware

Middleware is compiled into a single function per route — conditional await, shared next, short-circuit. It's baked into each route at registration time:

import { Server, cors, securityHeaders } from "@panmdaa/server";

const server = new Server();

server.use(cors({ allowOrigin: ["https://app.example.com"] }));
server.use(securityHeaders());
server.use(({ state, response }, next) => {   // custom middleware
  state.startedAt = performance.now();
  next();
});

server.get("/", ({ state, response }) => {
  response.json({ took: performance.now() - state.startedAt });
});

Two contracts make the chain work (see handler compilation):

• Not calling next() terminates the chain — how cors() short-circuits OPTIONS preflights.
• A sync middleware calling next() pays zero microtasks — handlers are only awaited when they actually return a thenable.

use() applies to routes registered after it, and to WebSocket routes too.

WebSockets

Path-only matching in a separate tree — server.ws("/*") never shadows HTTP routes. Zero-alloc parsing, zero-copy writes, cork'd coalescing:

import { Server, createWebSocketHeartbeat, CloseCode } from "@panmdaa/server";

const heartbeat = createWebSocketHeartbeat({ intervalMs: 30_000, timeoutMs: 10_000 });

const server = new Server({
  websocket: {                       // shared options for every WS route
    maxPayload: "8mb",
    perMessageDeflate: { threshold: "1kb" },
  },
});

server.ws("/chat", ({ socket }) => {
  heartbeat.track(socket);           // close dead connections
  socket.on("message", ({ data, isBinary }) => {
    socket.send(isBinary ? data : `echo: ${data}`);
  });
  socket.on("close", ({ code, reason, wasClean }) => { … });
});

socket.close(CloseCode.NormalClosure, "bye"); // graceful
socket.terminate();                           // hard kill

The handshake validates strictly (RFC 6455): Sec-WebSocket-Key, version 13, Connection: Upgrade. Messages are UTF-8 validated, maxPayload applies to the whole fragmented message and to the inflated size (decompression-bomb protection). Permessage-deflate always negotiates no-context-takeover and skips payloads that don't shrink. See the WebSocket docs.

HTTP/2 & TLS

One code path for HTTP/1, HTTP/2 and WebSocket-over-HTTP/2:

import { readFileSync } from "node:fs";
import { Server } from "@panmdaa/server";

const server = new Server({
  http2: true,                                    // h2c, or with tls → ALPN
  tls: { key: readFileSync("./key.pem"), cert: readFileSync("./cert.pem") },
  maxBodySize: "2mb",
  onError: (error) => console.error(error),
});

HTTP/2 requests are synthesized into the same request/response pipeline (createHttp2StreamRequest + Http2StreamResponse); extended CONNECT streams (:protocol: websocket) are intercepted for ws() routes. See HTTP/2.

Errors

Throw typed errors, get mapped responses — unknown errors become 500 automatically:

import {
  HttpError, NotFound, BadRequest,
  MethodNotAllowed, PayloadTooLarge, UnsupportedMediaType,
} from "@panmdaa/server";

server.get("/user/:id", ({ params }) => {
  throw new NotFound();
});

throw new BadRequest("Invalid credentials");
throw new MethodNotAllowed("PATCH");

HttpError(status, message?, description?, cause?) is the base; ~60 named subclasses are generated from STATUS_MESSAGES. The onError hook sees every error (including the 500s clients don't get). See Errors.

Request body

Lazy, cached, one representation per read:

server.post("/api/echo", async ({ body, response }) => {
  const raw  = await body.raw();         // Uint8Array
  const text = await body.text();        // string
  const json = await body.json();        // parsed — reuses text if decoded
  const buf  = await body.arrayBuffer(); // ArrayBuffer
  const form = await body.formData();    // FormData (urlencoded + multipart)
  const stream = await body.stream();    // web ReadableStream
  response.json({ received: json });
});

maxBodySize (default 16 MiB) rejects overflow with PayloadTooLarge (413) while streaming. Multipart is parsed with manual byte scanning — no regex, no per-part allocations. See Body.

API

Single entry point: everything — Server, contexts, handler compilation, Router/RadixTree, the WebSocket stack, errors, middleware — is exported from @panmdaa/server.

| Member | Description | |--------|-------------| | new Server(options?) | Native HTTP server (http/https/http2) + router + WS upgrader | | server.use(...mw) | Register middleware for routes added after this call | | server.get/post/put/delete/patch/options/head | Register a typed HTTP route | | server.all(path, ...h) | Same handler under every HTTP method | | server.query(path, ...h) | Body-capable route (no real HTTP method) | | server.ws(path, ...h) | Register a WebSocket route (path-only tree) | | server.group(prefix, fn) | Prefix + re-register child routes into the parent | | server.router(prefix?, router) | Mount an existing Router | | server.listen(port) / server.address() / server.close() | Native server controls | | ctx.params | Route params, typed by the path (Path<T>) | | ctx.query / ctx.cookies | Parsed query (duplicates → arrays) / cookies | | ctx.body | Lazy BodyContext (json/text/raw/formData/stream) | | ctx.response | Lazy ResponseContext — send/json/html/text/type/header/vary/file/download/stream/redirect/end, status property | | ctx.state | Lazy per-request shared object for middleware | | ctx.socket | WebSocketConnection on WS routes | | response.status | Mutable status property (default 200) — not a method | | response.file(path) / download(path) | Stream a file with Content-Length + mime | | cors(options) | CORS middleware (origin rules, preflight 204 short-circuit) | | securityHeaders() | Hardened security headers middleware | | createWebSocketHeartbeat(options) | Close unresponsive WS connections (track(socket)) | | CloseCode | Enum: NormalClosure, GoingAway, ProtocolError, … | | HttpError + subclasses | Typed errors mapped to status codes |

Internal architecture

src/
├── index.ts       ← root barrel — re-exports error, http, middleware, router, ws
├── router/       ← Router + three-tier RadixTree (static map / regex / trie)
├── http/
│   ├── handler/  ← compileHandler — generated middleware pipeline
│   ├── context/  ← ContextHandler, ContextHttpHandler, ContextBodyHandler
│   │   ├── body/     ← lazy BodyContext (raw/json/text/formData/multipart)
│   │   └── response/ ← lazy ResponseContext (auto Content-Length, file streaming)
│   └── server/   ← Server class + WebSocketUpgrader + native transport
├── ws/
│   ├── handshake/    ← RFC 6455 upgrade (HTTP/1 + HTTP/2 extended CONNECT)
│   ├── frame/        ← zero-alloc parser, builder, two-level unmask
│   ├── connection/   ← WebSocketConnection state machine
│   ├── compression/  ← permessage-deflate + zlib concurrency gate
│   └── heartbeat/    ← dead-connection sweeper (unref'd timers)
├── middleware/   ← cors, securityHeaders
└── error/        ← HttpError + generated status classes

Built on Node's native transport, zero runtime dependencies, pure ESM. Full internal documentation lives in docs/ — architecture, router internals, request lifecycle, WebSocket stack, and the design decisions behind every subsystem.

Scripts

| npm run | Description | |-----------|-------------| | build | Regenerate mime table, bundle with tsup (ESM + DTS) | | test | Run the test suite with vitest (HTTP, router, WebSocket, errors) | | typecheck | TypeScript strict check | | lint | Biome lint | | format | Biome format | | bench | Run all benchmarks (router, HTTP, middleware, parse, WS) |