kenojs

Keno

keno is a TypeScript-first server toolkit and modern client stack for building HTTP, WebSocket, and HTTP/2 applications with typed routing, familiar middleware, modular public imports, and scalable transport primitives.

Why Keno Exists

keno was created to keep the small-app experience pleasant without painting larger systems into a corner.

Many Node server stacks feel strong in one dimension and awkward in another:

• good routing, but no built-in story for WebSockets
• flexible middleware, but little help for host-aware routing or multi-listener setups
• good server ergonomics, but a disconnected client story

keno aims to keep one mental model across those layers instead:

• familiar app.use(...), app.get(...), and app.ws(...)
• typed route params and request helpers that stay pleasant in TypeScript
• modular subpath exports for tree-shakeable public imports
• built-in transport and concurrency primitives when an app grows past a single listener
• an HTTP client and WebSocket client that follow the same DX-first approach

Highlights

• Express-like HTTP routing and middleware chaining
• Typed route params inferred from path patterns
• Built-in request helpers for JSON, text, cookies, content negotiation, and host metadata
• Built-in response helpers for JSON, redirects, files, downloads, cookies, links, and cache headers
• WebSocket routing with protocol negotiation and permessage-deflate
• WebSocket rooms and heartbeat utilities
• Fetch-style HTTP client with middleware, retries, timeout, prepared requests, and typed route contracts
• WebSocket client for browser, Bun, and Node runtimes with a WebSocket implementation
• Host-aware routing with host(...) and domain(...)
• One app, multiple listeners through listenMany(...) and keno/multi-server
• Worker pools for CPU-bound endpoints
• Thread clustering with reusePort
• http, https, and http2 transports, including RFC 8441 extended CONNECT for WebSockets over HTTP/2
• Temporary TLS generation for local secure development
• Plugin system with built-in heartbeat, request logger, and OpenAPI plugins
• Public folder-based subpath imports such as keno/client, keno/middleware, and keno/worker-pool
• Benchmark harness and Autobahn WebSocket conformance runner in-repo

Project Health

• Contributing guide
• Code of Conduct
• Security Policy

Installation

npm install keno

Runtime notes:

• Server APIs target Node >=18.17.0
• The package is ESM-only
• The HTTP client works in fetch-compatible runtimes
• The WebSocket client works in browsers, Bun, and Node runtimes that provide globalThis.WebSocket, or with an injected constructor

Quick Start

import keno from "keno";

const app = keno();

app.use(keno.requestId());
app.use(keno.securityHeaders());
app.use(keno.json());

app.get("/users/:id", (request, response) => {
  response.json({
    id: request.params.id,
    requestId: response.locals.requestId,
    transport: request.transport,
  });
});

app.ws("/events", (socket) => {
  socket.sendText("ready");

  socket.on("text", (message) => {
    socket.sendText(`echo:${message}`);
  });
});

await app.listen(3000).ready();

HTTP Client Quick Start

import { createHttpClient } from "keno/client";

type User = {
  id: string;
  name: string;
};

const client = createHttpClient({
  baseURL: "https://api.myapp.com",
  headers: {
    authorization: "Bearer token",
  },
  timeout: 3000,
});

const user = await client
  .get("/users/:id", {
    params: {
      id: "42",
    },
  })
  .expectOk()
  .json<User>();

const prepared = client.get("/users/:id", {
  params: {
    id: "42",
  },
}).prepare();

const raw = await prepared.fetch();
console.log(user, raw.status);

Design Model

keno is centered on a small set of runtime building blocks:

• keno() and createApp()
  • Create an application instance with HTTP, WebSocket, plugin, and transport support.
• KenoRouter
  • Compose route trees and mount them under prefixes or host patterns.
• KenoRequest
  • Runtime request view with params, query, cookies, body parsing, and content negotiation helpers.
• KenoResponse
  • Chainable response builder for JSON, files, downloads, redirects, cookies, and headers.
• KenoWebSocket
  • Typed event-based WebSocket connection wrapper.
• HttpClient
  • Fetch-style client with fluent builders, middleware, retries, and typed route contracts.
• KenoWebSocketClient
  • Isomorphic reconnect-capable WebSocket client.

This keeps the everyday API small while still leaving room for host-aware routing, secure transports, concurrency, and shared contracts.

Public Imports

keno keeps the public surface modular through folder-based subpath exports:

• App and routing: keno, keno/application, keno/router, keno/request, keno/response, keno/types
• Middleware and plugins: keno/middleware, keno/plugins
• Clients and realtime: keno/client, keno/websocket
• Transport and concurrency: keno/certificates, keno/multi-server, keno/thread-cluster, keno/worker-pool

Example:

import { createApp } from "keno/application";
import { json, requestId } from "keno/middleware";
import { createHttpClient } from "keno/client";
import { createWorkerPool, threaded } from "keno/worker-pool";

const app = createApp();
const client = createHttpClient();

app.use(requestId());
app.use(json());

Routing And Middleware

The core router keeps a familiar shape on purpose:

import keno from "keno";

const app = keno();
const api = keno.Router();

app.use(async (request, response, next) => {
  const startedAt = Date.now();

  await next();

  console.log(request.method, request.path, response.statusCode, Date.now() - startedAt);
});

api.get("/users/:id", (request, response) => {
  response.json({
    id: request.params.id,
  });
});

app.use("/api", api);
app.host("api.local.test", api);

Built-in middleware today:

• cors(...)
• json(...)
• text(...)
• requestId(...)
• securityHeaders(...)
• serveStatic(...) and static(...)

Request And Response Helpers

Request helpers include:

• request.params, request.query, request.cookies, and request.body
• request.get(...), request.header(...), request.cookie(...), and request.param(...)
• request.accepts(...), request.acceptsLanguages(...), request.acceptsEncodings(...), and request.acceptsCharsets(...)
• request.is(...), request.xhr, and request.hasBody
• request.origin, request.host, request.hostname, request.ip, request.secure, and request.transport
• await request.buffer(), await request.text(), and await request.json<T>()

Response helpers include:

• response.status(...), response.type(...), response.json(...), and response.send(...)
• response.cookie(...) and response.clearCookie(...)
• response.redirect(...)
• await response.sendFile(...) and await response.download(...)
• response.links(...), response.vary(...), response.location(...), and response.attachment(...)
• response.set(...), response.append(...), response.remove(...), and response.sendStatus(...)

WebSockets

WebSocket routes use the same routing model as HTTP routes:

import keno from "keno";

const app = keno();
const rooms = keno.createWebSocketRooms();

app.ws("/chat/:room", (socket, request) => {
  const room = request.params.room;

  rooms.join(room, socket);
  socket.sendText(`joined:${room}`);

  socket.on("text", (message) => {
    rooms.broadcast(room, {
      message,
      room,
      type: "message",
    });
  });

  socket.on("close", () => {
    rooms.leave(socket);
  });
});

Realtime features currently available:

• app.ws(...) handlers with typed route params
• protocol negotiation during the handshake
• permessage-deflate support
• createWebSocketRooms() for room membership and broadcast
• createWebSocketHeartbeat() for keepalive management
• createWebSocketClient() in keno/client
• WebSocket over http, https, and http2

If your Node runtime does not expose globalThis.WebSocket, inject one explicitly:

import { WebSocket } from "ws";
import { createWebSocketClient } from "keno/client";

const client = createWebSocketClient("ws://127.0.0.1:3000/events", {
  WebSocket,
});

Plugins

Applications can register reusable behavior through plugins:

import keno from "keno";

const app = keno();

await app.register(keno.heartbeatPlugin, {
  details: () => ({
    region: "local",
    transport: "http",
  }),
  name: "public-api",
});

await app.register(keno.openApiPlugin, {
  title: "Public API Docs",
  document: {
    openapi: "3.1.0",
    info: {
      title: "Public API",
      version: "1.0.0",
    },
    paths: {},
  },
});

Built-in plugins:

• heartbeatPlugin
• openApiPlugin
• requestLoggerPlugin

Custom plugins can be defined with definePlugin(...).

HTTP Client

The HTTP client is designed to feel modern without getting in the way.

Fluent requests

import { createHttpClient } from "keno/client";

const client = createHttpClient({
  baseURL: "https://api.myapp.com",
});

const created = await client
  .post("/users", {
    body: {
      name: "Keno",
    },
  })
  .expect(201)
  .json<{ id: string; name: string }>();

Middleware, retries, timeout, and extend(...)

const client = createHttpClient({
  retry: {
    attempts: 3,
    baseDelayMs: 200,
  },
  timeout: 3000,
}).extend({
  baseURL: "https://api.myapp.com",
  headers: {
    authorization: "Bearer token",
  },
});

client.use(async (context, next) => {
  console.log("request", context.request.method, context.request.url);

  const response = await next();

  console.log("response", response.status);
  return response;
});

Prepared requests

Prepared requests are useful when you want keno to structure the request, but you want to decide later how to send it:

const prepared = client.prepare("GET", "/users/:id", {
  params: {
    id: "42",
  },
  query: {
    include: ["teams", "permissions"],
  },
});

const request = prepared.toRequest();
const raw = await prepared.fetch();
const response = await prepared.response();

console.log(request.url, raw.status, response.ok);

The fluent builder exposes the same preparation flow:

const prepared = client.get("/users/:id", {
  params: {
    id: "42",
  },
}).prepare();

Typed route contracts

Server and client code can share lightweight route definitions:

import {
  createHttpClient,
  defineHttpEndpoint,
  defineHttpRoute,
  defineHttpRoutes,
  type HttpClientSchemaFromRoutes,
} from "keno/client";

type CreateUser = {
  name: string;
};

type User = {
  id: string;
  name: string;
};

const routes = defineHttpRoutes(
  defineHttpRoute("/users/:id", {
    GET: defineHttpEndpoint<User, never, never, { id: string }>(),
  }),
  defineHttpRoute("/users", {
    POST: defineHttpEndpoint<User, CreateUser>(),
  }),
);

type Api = HttpClientSchemaFromRoutes<typeof routes>;

const client = createHttpClient<Api>({
  baseURL: "https://api.myapp.com",
});

const user = await client.GET("/users/:id", {
  params: {
    id: "42",
  },
});

const created = await client.POST("/users", {
  body: {
    name: "Ana",
  },
});

Transport And Concurrency

keno can stay minimal for a single-process app, but it also includes higher-level transport and concurrency primitives when needed.

Secure HTTP/2

import keno from "keno";
import { temporaryTls } from "keno/certificates";

const app = keno();
const tls = await temporaryTls({
  commonName: "127.0.0.1",
  hosts: ["127.0.0.1"],
});

await app.listen({
  host: "127.0.0.1",
  port: 3000,
  transport: "http2",
  allowHTTP1: true,
  tls,
}).ready();

Worker pool endpoints

import { createApp } from "keno/application";
import { createWorkerPool, threaded } from "keno/worker-pool";

const app = createApp();
const pool = createWorkerPool<{ value: number }, { result: number }>({
  entry: new URL("./worker.ts", import.meta.url),
  execArgv: ["--import", "tsx/esm"],
  size: 4,
});

app.get(
  "/cpu/:value",
  threaded(pool, {
    input: (request) => ({
      value: Number(request.params.value),
    }),
  }),
);

Other transport and concurrency features:

• listenMany(...) for one app behind multiple listeners
• keno/multi-server exports for explicit multi-listener orchestration
• createThreadCluster(...) in keno/thread-cluster
• threaded: true listener support with reusePort
• temporary TLS helpers in keno/certificates

Examples

The repository ships with runnable examples you can start directly from the project root.

Core HTTP:

• npm run example:basic
• npm run example:client-http
• npm run example:crud
• npm run example:hosts
• npm run example:modular-imports
• npm run example:multi-server
• npm run example:content-negotiation
• npm run example:webhook-text

Files and static delivery:

• npm run example:static-site
• npm run example:download-center

WebSocket and realtime:

• npm run example:client-websocket
• npm run example:websocket
• npm run example:realtime-chat
• npm run example:http2

Concurrency:

• npm run example:thread-cluster
• npm run example:threaded-endpoints

If one of the default ports is already in use, override it per run:

PORT=3100 npm run example:basic

More details live in examples/README.md.

Benchmarks And WebSocket Conformance

keno includes an in-repo benchmark harness and Autobahn runner.

Run the benchmark suite:

npm run bench

For a shorter pass:

npm run bench:quick

Run the Autobahn WebSocket conformance harness:

npm run autobahn

The benchmark harness currently covers:

• HTTP hello-world throughput
• CPU-bound route throughput
• static file throughput
• WebSocket echo throughput
• compressed WebSocket echo throughput

Current comparison targets include raw Node.js plus frameworks such as express, fastify, koa, tinyhttp, hono, ws, @fastify/websocket, and websocket.

Latest stored snapshot:

• Source: bench/results/latest.json
• Generated at: 2026-04-03T22:21:35.129Z
• Profile: duration=5s, connections=50, pipelining=1, wsClients=20, wsMessages=500, cpuValue=28

Benchmark numbers are environment-dependent, so treat them as a reproducible local snapshot rather than a universal ranking. The Vs keno column uses the plain keno server in the same benchmark group as the baseline.

HTTP Hello-World

Runtime	Req/s	Latency (ms)	Vs keno
keno	15325.60	3.04	1x
keno-plugin-stack	11165.60	4.08	0.73x
keno-threaded	39558.67	0.79	2.58x
node	17083.20	2.27	1.11x
express	10196	4.34	0.67x
fastify	14831.20	3.01	0.97x
koa	11700	3.78	0.76x
tinyhttp	12285.60	3.60	0.80x
hono	14005.60	3.06	0.91x

CPU-Bound Route

Runtime	Req/s	Latency (ms)	Vs keno
keno	290	175.22	1x
keno-worker-pool	1042.34	47.28	3.59x
keno-threaded	1011.50	48.73	3.49x
node	285	180.06	0.98x
express	290	177.21	1x
fastify	290	175.59	1x
koa	285	178.35	0.98x
tinyhttp	290	173.33	1x
hono	290	172.65	1x

Static File

Runtime	Req/s	Latency (ms)	Vs keno
keno	13074.67	3.17	1x
keno-threaded	26235.20	1.39	2.01x
node	7489.20	6.20	0.57x
express	7130.80	6.47	0.55x
fastify	7494	6.15	0.57x
koa	5009.20	9.49	0.38x
tinyhttp	7120.40	6.48	0.54x

WebSocket Echo

Runtime	Msgs/s	Duration (ms)	Vs keno
keno	26282.55	380.48	1x
keno-rooms	27957.90	357.68	1.06x
keno-threaded	47797.39	209.22	1.82x
ws	34734.30	287.90	1.32x
fastify-websocket	34821.78	287.18	1.32x
websocket	28844.27	346.69	1.10x

WebSocket Compressed Echo

Runtime	Msgs/s	Duration (ms)	Vs keno
keno	7475.16	1337.76	1x
keno-rooms	7809.26	1280.53	1.04x
keno-threaded	11070.89	903.27	1.48x
ws	9938.65	1006.17	1.33x
fastify-websocket	11629.25	859.90	1.56x

More details live in bench/README.md.

Validation

The repository is validated with:

• npm run typecheck
• npm test
• npm run build

For the full local gate:

npm run check