@jongleberry/api-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonathan Ong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# @jongleberry/api-server
+
+A lightweight Node.js HTTP server library built on a trie router with automatic compression, ETag caching, streaming, and a dev-friendly request logger.
+
+## Install
+
+```sh
+npm install @jongleberry/api-server
+```
+
+Requires Node.js ≥ 24.
+
+## Quick start
+
+```ts
+import http from "node:http";
+import { Application } from "@jongleberry/api-server";
+
+const app = new Application();
+
+app.route("/hello").get((ctx) => {
+  ctx.json({ hello: "world" });
+});
+
+app.route("/users/:id").get((ctx) => {
+  ctx.json({ id: ctx.params.id });
+});
+
+http.createServer(app.callback()).listen(3000);
+```
+
+Or use the factory shorthand:
+
+```ts
+import { createApp } from "@jongleberry/api-server";
+
+const app = createApp();
+app.route("/").get((ctx) => ctx.json({ ok: true }));
+```
+
+## Features
+
+- **Trie router** — `find-my-way` under the hood; zero regex overhead on the hot path
+- **Buffered responses** — `ctx.json()`, `ctx.response.text()`, `.html()`, `.xml()`, `.buffer()`
+- **Streaming** — `ctx.pipeline(readable, ...transforms)` with back-pressure and error propagation
+- **Automatic ETag** — SHA-256 ETag on every buffered 2xx; `If-None-Match` → 304
+- **Compression** — `br` / `gzip` / `deflate` negotiation; 1 KB threshold; `SYNC_FLUSH` for streams
+- **Server-Timing** — response latency as a `Server-Timing` header (buffered) or trailer (streaming)
+- **Abort signals** — `ctx.signal` / `ctx.abortController` wired to client disconnect
+- **AsyncLocalStorage** — per-request store via `app.setAsyncLocalStorage(als)`
+- **Cookies** — `ctx.cookies.get()` / `.set()` with full `Set-Cookie` options
+- **Cache-Control** — `ctx.cacheControl(visibility, maxAge)` helper
+- **Trusted client IP** — Cloudflare/AWS ALB-aware helper for Node, Deno, and Bun
+- **Dev logger** — concurrent-request bar, color-coded status codes, timing thresholds; silent in `NODE_ENV=production` and `NODE_ENV=test`
+- **Error safety net** — error handlers that throw or return without a response still guarantee the client receives a response
+
+## Requirements
+
+- Node.js ≥ 24.0.0
+- ESM (`"type": "module"` or `.mjs` imports)
+
+## Documentation
+
+See [docs/](docs/README.md) for full API reference:
+
+| Topic                                              | Description                                         |
+| -------------------------------------------------- | --------------------------------------------------- |
+| [Getting started](docs/getting-started.md)         | Install, hello world, mounting on http.createServer |
+| [Routing](docs/routing.md)                         | Route registration, params, notFoundHandler         |
+| [Context](docs/context.md)                         | Full `ctx` API surface                              |
+| [Request](docs/request.md)                         | Body parsing, size limits, content-type detection   |
+| [Response](docs/response.md)                       | Buffered and streaming responses                    |
+| [ETag and caching](docs/etag-and-caching.md)       | Automatic ETags, 304s, Cache-Control                |
+| [Compression](docs/compression.md)                 | br/gzip/deflate negotiation                         |
+| [Server-Timing](docs/server-timing.md)             | Response latency headers and trailers               |
+| [Cookies](docs/cookies.md)                         | Reading and writing cookies                         |
+| [Error handling](docs/error-handling.md)           | errorHandler, notFoundHandler, http-errors          |
+| [Async local storage](docs/async-local-storage.md) | Per-request store                                   |
+| [Abort signals](docs/abort-signals.md)             | Client-disconnect propagation                       |
+| [Logger](docs/logger.md)                           | Dev logger configuration                            |
+| [Trusted client IP](docs/trusted-client-ip.md)     | Node, Deno, and Bun client IP helpers               |
+| [Extending context](docs/extending-context.md)     | Adding methods to ctx                               |
+| [Testing](docs/testing.md)                         | Testing patterns with vitest and supertest          |
+
+## Design
+
+- No middleware stack. Routes are registered directly on the application; request processing runs top-to-bottom in a single async function per request.
+- No magic. `ctx.req` and `ctx.res` are the raw Node.js `IncomingMessage` and `ServerResponse` objects.
+- Body is pull-based. `ctx.request.buffer()` and `ctx.request.json()` are explicit calls; the body is never automatically parsed.
+- Responses are explicit. You choose buffered or streaming; the library doesn't buffer a stream or stream a buffer behind your back.
+
+## License
+
+MIT © Jonathan Ong 2026

package/dist/application.d.mts

@@ -0,0 +1,27 @@
+import { EventEmitter } from "node:events";
+import type { RequestListener } from "node:http";
+import type { AsyncLocalStorage } from "node:async_hooks";
+import { Context } from "./context.mts";
+import { type RouteBuilder } from "./router.mts";
+import type { ApplicationOptions } from "./types.mts";
+export type ErrorHandler = (ctx: Context, error: Error) => Promise<void> | void;
+export type NotFoundHandler = (ctx: Context) => Promise<void> | void;
+export declare class Application extends EventEmitter {
+    private router;
+    private errorHandlerFn;
+    private notFoundHandlerFn;
+    private asyncLocalStorage;
+    private extensions;
+    private contextClass;
+    private logger;
+    constructor(options?: ApplicationOptions);
+    route(path: string): RouteBuilder;
+    errorHandler(fn: ErrorHandler): void;
+    notFoundHandler(fn: NotFoundHandler): void;
+    setAsyncLocalStorage(als: AsyncLocalStorage<unknown>): void;
+    extend(methods: Record<string, unknown>): void;
+    callback(): RequestListener;
+    private handleRequest;
+    private runRequest;
+}
+export declare const createApp: (options?: ApplicationOptions) => Application;

package/dist/application.mjs

@@ -0,0 +1,134 @@
+import { EventEmitter } from "node:events";
+import { Context, createContextClass } from "./context.mjs";
+import { createRouteBuilder } from "./router.mjs";
+import Router from "find-my-way";
+import { ServerTiming } from "./server-timing.mjs";
+import { Logger } from "./logger.mjs";
+import { getFallbackStatus, sendFallback } from "./fallback-response.mjs";
+export class Application extends EventEmitter {
+    router = Router();
+    errorHandlerFn = null;
+    notFoundHandlerFn = null;
+    asyncLocalStorage = null;
+    extensions = {};
+    contextClass = Context;
+    logger;
+    constructor(options) {
+        super();
+        this.logger = new Logger(options?.logger);
+    }
+    route(path) {
+        return createRouteBuilder(this.router, path);
+    }
+    errorHandler(fn) {
+        this.errorHandlerFn = fn;
+    }
+    notFoundHandler(fn) {
+        this.notFoundHandlerFn = fn;
+    }
+    setAsyncLocalStorage(als) {
+        this.asyncLocalStorage = als;
+    }
+    extend(methods) {
+        Object.assign(this.extensions, methods);
+        this.contextClass = createContextClass(this.extensions);
+    }
+    callback() {
+        return (req, res) => {
+            this.handleRequest(req, res);
+        };
+    }
+    handleRequest(req, res) {
+        const run = () => this.runRequest(req, res).catch((err) => {
+            // Safety net: if runRequest rejects before its own try-catch (e.g. during
+            // context/timing setup), ensure the client always gets a response instead
+            // of a socket hang-up from an unhandled promise rejection.
+            const error = err instanceof Error ? err : new Error(String(err));
+            try {
+                if (this.listenerCount("error") > 0) {
+                    this.emit("error", error);
+                }
+            }
+            catch {
+                // Swallow listener throws so the 500 response still goes out.
+            }
+            if (!res.headersSent) {
+                res.writeHead(500);
+                res.end("Internal Server Error");
+            }
+        });
+        if (this.asyncLocalStorage) {
+            this.asyncLocalStorage.run({}, run);
+        }
+        else {
+            run();
+        }
+    }
+    async runRequest(req, res) {
+        const abortController = new AbortController();
+        const timing = new ServerTiming();
+        const ContextClass = this.contextClass;
+        req.on("close", () => {
+            if (!res.writableEnded) {
+                abortController.abort();
+            }
+        });
+        const { onWriteHead, onFinish } = this.logger.onRequestStart(req);
+        const ctx = new ContextClass(req, res, {}, timing, this.asyncLocalStorage, abortController, onWriteHead);
+        // Security headers
+        res.setHeader("X-XSS-Protection", "0");
+        res.setHeader("X-Frame-Options", "SAMEORIGIN");
+        res.setHeader("X-Content-Type-Options", "nosniff");
+        try {
+            const method = req.method ?? "GET";
+            const url = req.url ?? "/";
+            const rawPath = url.startsWith("http://") || url.startsWith("https://")
+                ? new URL(url).pathname
+                : url.split("?")[0];
+            const routePath = rawPath.replace(/^\/+/, "/") || "/";
+            const found = this.router.find(method, routePath);
+            if (found) {
+                ctx.params = found.params;
+                await found.handler(req, res, found.params, ctx, found.searchParams);
+            }
+            if (!ctx.response.sent) {
+                if (this.notFoundHandlerFn) {
+                    await this.notFoundHandlerFn(ctx);
+                }
+                else {
+                    res.writeHead(404);
+                    res.end("Not Found");
+                }
+            }
+            onFinish(res.statusCode);
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            if (this.listenerCount("error") > 0) {
+                this.emit("error", error);
+            }
+            if (this.errorHandlerFn) {
+                try {
+                    await this.errorHandlerFn(ctx, error);
+                }
+                catch (handlerErr) {
+                    if (this.listenerCount("error") > 0) {
+                        this.emit("error", handlerErr);
+                    }
+                }
+                // Safety net: ensure the client always receives a response, even if the
+                // registered error handler threw or returned without sending one. Without
+                // this, requests hang until the socket times out (issue #1948).
+                if (!res.headersSent) {
+                    sendFallback(res);
+                }
+            }
+            else if (!res.headersSent) {
+                res.writeHead(getFallbackStatus(error));
+                res.end(error.message);
+            }
+            onFinish(res.statusCode);
+        }
+    }
+}
+export const createApp = (options) => new Application(options);

package/dist/cache-control.d.mts

@@ -0,0 +1,2 @@
+import type { ServerResponse } from "node:http";
+export declare function applyCacheControl(res: ServerResponse, type: "public" | "private", ttl?: number | string): void;

package/dist/cache-control.mjs

@@ -0,0 +1,40 @@
+const TIME_UNITS = {
+    second: 1,
+    seconds: 1,
+    minute: 60,
+    minutes: 60,
+    hour: 3600,
+    hours: 3600,
+    day: 86400,
+    days: 86400,
+    week: 604800,
+    weeks: 604800,
+    month: 2592000,
+    months: 2592000,
+    year: 31536000,
+    years: 31536000,
+};
+function parseTtl(ttl) {
+    if (typeof ttl === "number")
+        return ttl;
+    const match = /^(\d+)\s+(\w+)$/.exec(ttl.trim());
+    if (!match)
+        throw new Error(`Invalid TTL format: "${ttl}"`);
+    const amount = Number.parseInt(match[1], 10);
+    const unit = match[2].toLowerCase();
+    const multiplier = TIME_UNITS[unit];
+    if (multiplier === undefined)
+        throw new Error(`Unknown TTL unit: "${match[2]}"`);
+    return amount * multiplier;
+}
+export function applyCacheControl(res, type, ttl) {
+    if (type === "public") {
+        if (ttl === undefined)
+            throw new Error("TTL is required for public cache control");
+        const maxAge = parseTtl(ttl);
+        res.setHeader("Cache-Control", `public, max-age=${maxAge}`);
+    }
+    else {
+        res.setHeader("Cache-Control", "private, no-cache, no-store, must-revalidate");
+    }
+}

package/dist/compression.d.mts

@@ -0,0 +1,9 @@
+import zlib from "node:zlib";
+import type { IncomingMessage } from "node:http";
+export declare function negotiateEncoding(req: IncomingMessage): string | null;
+export declare function isCompressible(contentType: string): boolean;
+export declare function createCompressStream(encoding: string): zlib.BrotliCompress | zlib.Gzip | zlib.Deflate;
+export declare function compressSync(encoding: string, buffer: Buffer): Buffer;
+export declare function shouldCompress(req: IncomingMessage, res: {
+    getHeader(name: string): string | number | string[] | undefined;
+}, contentType: string, bodyLength: number): string | null;

package/dist/compression.mjs

@@ -0,0 +1,49 @@
+import zlib from "node:zlib";
+// @ts-ignore
+import Negotiator from "negotiator";
+// @ts-ignore
+import compressibleFn from "compressible";
+const SUPPORTED_ENCODINGS = ["br", "gzip", "deflate"];
+const COMPRESSION_THRESHOLD = 1024;
+export function negotiateEncoding(req) {
+    const negotiator = new Negotiator(req);
+    const encoding = negotiator.encoding(SUPPORTED_ENCODINGS);
+    if (!encoding || encoding === "identity")
+        return null;
+    return encoding;
+}
+export function isCompressible(contentType) {
+    return compressibleFn(contentType) === true;
+}
+export function createCompressStream(encoding) {
+    if (encoding === "br") {
+        return zlib.createBrotliCompress({
+            flush: zlib.constants.BROTLI_OPERATION_FLUSH,
+        });
+    }
+    if (encoding === "gzip") {
+        return zlib.createGzip({ flush: zlib.constants.Z_SYNC_FLUSH });
+    }
+    return zlib.createDeflate({ flush: zlib.constants.Z_SYNC_FLUSH });
+}
+export function compressSync(encoding, buffer) {
+    if (encoding === "br") {
+        return zlib.brotliCompressSync(buffer);
+    }
+    if (encoding === "gzip") {
+        return zlib.gzipSync(buffer);
+    }
+    return zlib.deflateSync(buffer);
+}
+export function shouldCompress(req, res, contentType, bodyLength) {
+    if (bodyLength < COMPRESSION_THRESHOLD)
+        return null;
+    if (res.getHeader("Content-Encoding"))
+        return null;
+    const cacheControl = req.headers["cache-control"];
+    if (cacheControl && cacheControl.includes("no-transform"))
+        return null;
+    if (!isCompressible(contentType))
+        return null;
+    return negotiateEncoding(req);
+}

package/dist/context.d.mts

@@ -0,0 +1,32 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { AsyncLocalStorage } from "node:async_hooks";
+import httpAssert from "http-assert";
+import { Request } from "./request.mts";
+import { Response } from "./response.mts";
+import { Cookies } from "./cookies.mts";
+import type { ServerTiming } from "./server-timing.mts";
+export declare class Context {
+    req: IncomingMessage;
+    res: ServerResponse;
+    params: Record<string, string | undefined>;
+    request: Request;
+    response: Response;
+    cookies: Cookies;
+    signal: AbortSignal;
+    abortController: AbortController;
+    assert: typeof httpAssert;
+    private queryCache;
+    private asyncLocalStorage;
+    constructor(req: IncomingMessage, res: ServerResponse, params: Record<string, string | undefined>, timing: ServerTiming, als: AsyncLocalStorage<unknown> | null, abortController: AbortController, onWriteHead?: () => void);
+    get query(): Record<string, string | string[]>;
+    get store(): unknown;
+    get ip(): string | undefined;
+    set(header: string, value: string): void;
+    setType(type: string): void;
+    setStatus(code: number): void;
+    throw(status: number, message?: string, code?: string): never;
+    json(data: unknown): void;
+    pipeline(source: NodeJS.ReadableStream, ...transforms: NodeJS.ReadWriteStream[]): Promise<void>;
+    cacheControl(type: "public" | "private", ttl?: number | string): void;
+}
+export declare function createContextClass(extensions: Record<string, unknown>): typeof Context;

package/dist/context.mjs

@@ -0,0 +1,102 @@
+import httpAssert from "http-assert";
+import createHttpError from "http-errors";
+import { Request } from "./request.mjs";
+import { Response } from "./response.mjs";
+import { Cookies } from "./cookies.mjs";
+import { applyCacheControl } from "./cache-control.mjs";
+import { resolveTrustedClientIp } from "./trusted-client-ip.mjs";
+const CONTENT_TYPES = {
+    json: "application/json; charset=utf-8",
+    html: "text/html; charset=utf-8",
+    text: "text/plain; charset=utf-8",
+    xml: "application/xml; charset=utf-8",
+    bin: "application/octet-stream",
+    form: "application/x-www-form-urlencoded",
+};
+export class Context {
+    req;
+    res;
+    params;
+    request;
+    response;
+    cookies;
+    signal;
+    abortController;
+    assert;
+    queryCache = null;
+    asyncLocalStorage;
+    constructor(req, res, params, timing, als, abortController, onWriteHead) {
+        this.req = req;
+        this.res = res;
+        this.params = params;
+        this.request = new Request(req, res);
+        this.response = new Response(req, res, timing, onWriteHead);
+        this.cookies = new Cookies(req, res);
+        this.abortController = abortController;
+        this.signal = abortController.signal;
+        this.assert = httpAssert;
+        this.asyncLocalStorage = als;
+    }
+    get query() {
+        if (this.queryCache)
+            return this.queryCache;
+        const url = this.req.url ?? "";
+        const questionMark = url.indexOf("?");
+        if (questionMark === -1) {
+            this.queryCache = {};
+            return this.queryCache;
+        }
+        const queryString = url.slice(questionMark + 1);
+        const params = new URLSearchParams(queryString);
+        const result = {};
+        for (const key of params.keys()) {
+            const values = params.getAll(key);
+            result[key] = values.length === 1 ? values[0] : values;
+        }
+        this.queryCache = result;
+        return this.queryCache;
+    }
+    get store() {
+        return this.asyncLocalStorage?.getStore();
+    }
+    get ip() {
+        return resolveTrustedClientIp({
+            headers: this.req.headers,
+            socketRemoteAddress: this.req.socket?.remoteAddress,
+        });
+    }
+    set(header, value) {
+        this.res.setHeader(header, value);
+    }
+    setType(type) {
+        this.res.setHeader("Content-Type", CONTENT_TYPES[type] ?? type);
+    }
+    setStatus(code) {
+        this.response.setStatus(code);
+        if (code === 204 || code === 205) {
+            this.response.empty();
+        }
+    }
+    throw(status, message, code) {
+        const err = message !== undefined ? createHttpError(status, message) : createHttpError(status);
+        if (code !== undefined) {
+            Object.assign(err, { code });
+        }
+        throw err;
+    }
+    json(data) {
+        this.response.json(data);
+    }
+    pipeline(source, ...transforms) {
+        return this.response.pipeline(source, ...transforms);
+    }
+    cacheControl(type, ttl) {
+        applyCacheControl(this.res, type, ttl);
+    }
+}
+export function createContextClass(extensions) {
+    class ExtendedContext extends Context {
+    }
+    Object.assign(ExtendedContext.prototype, extensions);
+    return ExtendedContext;
+}

package/dist/cookies.d.mts

@@ -0,0 +1,10 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { CookieOptions } from "./types.mts";
+export declare class Cookies {
+    private req;
+    private res;
+    private parsed;
+    constructor(req: IncomingMessage, res: ServerResponse);
+    get(name: string): string | undefined;
+    set(name: string, value: string, opts?: CookieOptions): void;
+}

package/dist/cookies.mjs

@@ -0,0 +1,30 @@
+import { parse, serialize } from "cookie";
+export class Cookies {
+    req;
+    res;
+    parsed = null;
+    constructor(req, res) {
+        this.req = req;
+        this.res = res;
+    }
+    get(name) {
+        if (!this.parsed) {
+            const header = this.req.headers.cookie ?? "";
+            this.parsed = parse(header);
+        }
+        return this.parsed[name];
+    }
+    set(name, value, opts) {
+        const existing = this.res.getHeader("Set-Cookie");
+        const serialized = serialize(name, value, opts);
+        if (Array.isArray(existing)) {
+            this.res.setHeader("Set-Cookie", [...existing, serialized]);
+        }
+        else if (existing) {
+            this.res.setHeader("Set-Cookie", [String(existing), serialized]);
+        }
+        else {
+            this.res.setHeader("Set-Cookie", serialized);
+        }
+    }
+}

package/dist/etag.d.mts

@@ -0,0 +1,3 @@
+import type { IncomingMessage } from "node:http";
+export declare function generateETag(body: Buffer): string;
+export declare function isFresh(req: IncomingMessage, etag: string): boolean;

package/dist/etag.mjs

@@ -0,0 +1,17 @@
+import crypto from "node:crypto";
+export function generateETag(body) {
+    const hash = crypto.createHash("sha256").update(body).digest("base64url");
+    return `"${hash}"`;
+}
+export function isFresh(req, etag) {
+    const method = req.method ?? "GET";
+    if (method !== "GET" && method !== "HEAD")
+        return false;
+    const ifNoneMatch = req.headers["if-none-match"];
+    if (!ifNoneMatch)
+        return false;
+    if (ifNoneMatch === "*")
+        return true;
+    const tags = ifNoneMatch.split(",").map((t) => t.trim());
+    return tags.includes(etag);
+}

package/dist/fallback-response.d.mts

@@ -0,0 +1,3 @@
+import type { ServerResponse } from "node:http";
+export declare function sendFallback(res: ServerResponse): void;
+export declare function getFallbackStatus(error: unknown): number;

package/dist/fallback-response.mjs

@@ -0,0 +1,18 @@
+const FALLBACK_STATUS = 404;
+const FALLBACK_BODY = "Not Found";
+export function sendFallback(res) {
+    try {
+        res.writeHead(FALLBACK_STATUS);
+        res.end(FALLBACK_BODY);
+    }
+    catch {
+        // Socket may already be destroyed; nothing more we can do.
+    }
+}
+export function getFallbackStatus(error) {
+    const status = error?.status;
+    if (typeof status === "number" && Number.isInteger(status) && status >= 100 && status < 600) {
+        return status;
+    }
+    return FALLBACK_STATUS;
+}

package/dist/index.d.mts

@@ -0,0 +1,14 @@
+export * from "./application.mts";
+export type { ErrorHandler, NotFoundHandler } from "./application.mts";
+export * from "./context.mts";
+export * from "./request.mts";
+export * from "./response.mts";
+export * from "./cookies.mts";
+export * from "./server-timing.mts";
+export * from "./logger.mts";
+export type { LoggerOptions } from "./logger.mts";
+export * from "./etag.mts";
+export * from "./cache-control.mts";
+export * from "./compression.mts";
+export type { Handler, RouteBuilder } from "./router.mts";
+export type { CookieOptions, ApplicationOptions } from "./types.mts";

package/dist/index.mjs

@@ -0,0 +1,10 @@
+export * from "./application.mjs";
+export * from "./context.mjs";
+export * from "./request.mjs";
+export * from "./response.mjs";
+export * from "./cookies.mjs";
+export * from "./server-timing.mjs";
+export * from "./logger.mjs";
+export * from "./etag.mjs";
+export * from "./cache-control.mjs";
+export * from "./compression.mjs";

package/dist/logger.d.mts

@@ -0,0 +1,32 @@
+import type { IncomingMessage } from "node:http";
+export interface LoggerOptions {
+    timingThresholds?: {
+        yellow: number;
+        orange: number;
+        red: number;
+    };
+}
+interface RequestLogger {
+    onWriteHead: () => void;
+    onFinish: (status: number) => void;
+}
+export declare class Logger {
+    private enabled;
+    private level;
+    private thresholds;
+    private activeSlots;
+    private highWaterMark;
+    constructor(options?: LoggerOptions);
+    isEnabled(): boolean;
+    onRequestStart(req: IncomingMessage): RequestLogger;
+    private createErrorLevelLogger;
+    private assignSlot;
+    private freeSlot;
+    private print;
+    private renderBar;
+    private elapsedMs;
+    private formatTiming;
+    private colorStatus;
+    private colorTiming;
+}
+export {};

package/dist/logger.mjs

@@ -0,0 +1,111 @@
+const RESET = "\x1b[0m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const RED = "\x1b[31m";
+const CYAN = "\x1b[36m";
+const ORANGE = "\x1b[38;5;208m";
+const DEFAULT_THRESHOLDS = { yellow: 50, orange: 250, red: 500 };
+export class Logger {
+    enabled;
+    level;
+    thresholds;
+    activeSlots = new Map();
+    highWaterMark = 0;
+    constructor(options = {}) {
+        const env = process.env.NODE_ENV;
+        this.enabled = env !== "production" && env !== "test";
+        this.level = process.env.LOG_LEVEL === "info" ? "info" : "error";
+        this.thresholds = { ...DEFAULT_THRESHOLDS, ...options.timingThresholds };
+    }
+    isEnabled() {
+        return this.enabled;
+    }
+    onRequestStart(req) {
+        if (!this.enabled)
+            return { onWriteHead: noop, onFinish: noop };
+        if (this.level === "error") {
+            return this.createErrorLevelLogger(req);
+        }
+        const slot = this.assignSlot();
+        const method = req.method ?? "GET";
+        const url = req.url ?? "/";
+        const startTime = process.hrtime.bigint();
+        this.print("──‣", "┈┈┈┈┈", method, url, "┬", slot);
+        return {
+            onWriteHead: () => {
+                const ms = this.elapsedMs(startTime);
+                this.print("···", this.colorTiming(ms, this.formatTiming(ms)), method, url, "·", slot);
+            },
+            onFinish: (status) => {
+                const ms = this.elapsedMs(startTime);
+                this.freeSlot(slot);
+                this.print(this.colorStatus(status, String(status)), this.colorTiming(ms, this.formatTiming(ms)), method, url, "┴", slot);
+            },
+        };
+    }
+    createErrorLevelLogger(req) {
+        const method = req.method ?? "GET";
+        const url = req.url ?? "/";
+        const startTime = process.hrtime.bigint();
+        return {
+            onWriteHead: noop,
+            onFinish: (status) => {
+                if (status >= 500) {
+                    const ms = this.elapsedMs(startTime);
+                    process.stdout.write(`${RED}${status}${RESET} ${this.colorTiming(ms, this.formatTiming(ms))} ${method} ${url}\n`);
+                }
+            },
+        };
+    }
+    assignSlot() {
+        let slot = 0;
+        while (this.activeSlots.has(slot))
+            slot++;
+        this.activeSlots.set(slot, true);
+        if (slot + 1 > this.highWaterMark)
+            this.highWaterMark = slot + 1;
+        return slot;
+    }
+    freeSlot(slot) {
+        this.activeSlots.delete(slot);
+        while (this.highWaterMark > 0 && !this.activeSlots.has(this.highWaterMark - 1)) {
+            this.highWaterMark--;
+        }
+    }
+    print(statusStr, timingStr, method, url, slotChar, slotIndex) {
+        const bar = this.renderBar(slotChar, slotIndex);
+        process.stdout.write(`${statusStr} ${timingStr} ${method}┈ ${bar} ${url}\n`);
+    }
+    renderBar(eventChar, eventSlot) {
+        const parts = [];
+        for (let i = 0; i < this.highWaterMark; i++) {
+            parts.push(i === eventSlot ? eventChar : this.activeSlots.has(i) ? "│" : "┈");
+        }
+        return parts.join("┈");
+    }
+    elapsedMs(startTime) {
+        return Number(process.hrtime.bigint() - startTime) / 1_000_000;
+    }
+    formatTiming(ms) {
+        return `${Math.round(ms)}ms`.padStart(5, "┈");
+    }
+    colorStatus(status, str) {
+        if (status >= 500)
+            return `${RED}${str}${RESET}`;
+        if (status >= 400)
+            return `${ORANGE}${str}${RESET}`;
+        if (status >= 300)
+            return `${CYAN}${str}${RESET}`;
+        return `${GREEN}${str}${RESET}`;
+    }
+    colorTiming(ms, str) {
+        if (ms >= this.thresholds.red)
+            return `${RED}${str}${RESET}`;
+        if (ms >= this.thresholds.orange)
+            return `${ORANGE}${str}${RESET}`;
+        if (ms >= this.thresholds.yellow)
+            return `${YELLOW}${str}${RESET}`;
+        return str;
+    }
+}
+function noop() { }

package/dist/request.d.mts

@@ -0,0 +1,10 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+export declare class Request {
+    private req;
+    private res;
+    private bodyPromise;
+    constructor(req: IncomingMessage, res: ServerResponse);
+    is(type: string | string[]): string | false | null;
+    buffer(limit?: string | number): Promise<Buffer>;
+    json<T = unknown>(limit?: string | number): Promise<T>;
+}

package/dist/request.mjs

@@ -0,0 +1,74 @@
+// @ts-ignore
+import typeIs from "type-is";
+// @ts-ignore
+import bytes from "bytes";
+function noop() { }
+export class Request {
+    req;
+    res;
+    bodyPromise = null;
+    constructor(req, res) {
+        this.req = req;
+        this.res = res;
+    }
+    is(type) {
+        return typeIs(this.req, Array.isArray(type) ? type : [type]);
+    }
+    buffer(limit) {
+        if (!this.bodyPromise) {
+            if (this.req.headers.expect === "100-continue") {
+                this.res.writeContinue();
+            }
+            this.bodyPromise = readBody(this.req, limit);
+        }
+        return this.bodyPromise;
+    }
+    async json(limit) {
+        const buf = await this.buffer(limit);
+        try {
+            return JSON.parse(buf.toString("utf8"));
+        }
+        catch {
+            throw Object.assign(new Error("Invalid JSON"), { status: 400 });
+        }
+    }
+}
+function readBody(req, limit) {
+    return new Promise((resolve, reject) => {
+        const maxBytes = limit !== undefined ? (bytes.parse(limit) ?? Infinity) : Infinity;
+        const chunks = [];
+        let totalLength = 0;
+        function cleanup() {
+            req.removeListener("data", onData);
+            req.removeListener("end", onEnd);
+            req.removeListener("error", onError);
+        }
+        function onData(chunk) {
+            totalLength += chunk.length;
+            if (totalLength > maxBytes) {
+                // Remove data/end listeners but keep a no-op error handler during drain
+                // to prevent unhandled 'error' events from crashing the process.
+                req.removeListener("data", onData);
+                req.removeListener("end", onEnd);
+                req.removeListener("error", onError);
+                req.on("error", noop);
+                reject(Object.assign(new Error("Request entity too large"), { status: 413 }));
+                // Drain remaining data so the connection stays reusable (HTTP keep-alive)
+                req.resume();
+                return;
+            }
+            chunks.push(chunk);
+        }
+        function onEnd() {
+            cleanup();
+            resolve(Buffer.concat(chunks));
+        }
+        function onError(err) {
+            cleanup();
+            reject(err);
+        }
+        req.on("data", onData);
+        req.on("end", onEnd);
+        req.on("error", onError);
+    });
+}

package/dist/response.d.mts

@@ -0,0 +1,21 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { ServerTiming } from "./server-timing.mts";
+export declare class Response {
+    private req;
+    private res;
+    private timing;
+    private responseSent;
+    private statusCode;
+    private onWriteHeadCallback;
+    constructor(req: IncomingMessage, res: ServerResponse, timing: ServerTiming, onWriteHead?: () => void);
+    setStatus(code: number): void;
+    get sent(): boolean;
+    json(data: unknown): void;
+    text(data: string): void;
+    html(data: string): void;
+    xml(data: string): void;
+    buffer(data: Buffer, contentType: string): void;
+    pipeline(source: NodeJS.ReadableStream, ...transforms: NodeJS.ReadWriteStream[]): Promise<void>;
+    empty(): void;
+    private sendBuffered;
+}

package/dist/response.mjs

@@ -0,0 +1,124 @@
+import { pipeline } from "node:stream/promises";
+import { generateETag, isFresh } from "./etag.mjs";
+import { shouldCompress, createCompressStream, compressSync } from "./compression.mjs";
+export class Response {
+    req;
+    res;
+    timing;
+    responseSent = false;
+    statusCode = 200;
+    // Only called for non-HEAD streaming responses (pipeline), not buffered or HEAD
+    onWriteHeadCallback = null;
+    constructor(req, res, timing, onWriteHead) {
+        this.req = req;
+        this.res = res;
+        this.timing = timing;
+        this.onWriteHeadCallback = onWriteHead ?? null;
+    }
+    setStatus(code) {
+        this.statusCode = code;
+    }
+    get sent() {
+        return this.responseSent;
+    }
+    json(data) {
+        const body = Buffer.from(JSON.stringify(data), "utf8");
+        this.sendBuffered(body, "application/json; charset=utf-8");
+    }
+    text(data) {
+        const body = Buffer.from(data, "utf8");
+        this.sendBuffered(body, "text/plain; charset=utf-8");
+    }
+    html(data) {
+        const body = Buffer.from(data, "utf8");
+        this.sendBuffered(body, "text/html; charset=utf-8");
+    }
+    xml(data) {
+        const body = Buffer.from(data, "utf8");
+        this.sendBuffered(body, "application/xml; charset=utf-8");
+    }
+    buffer(data, contentType) {
+        this.sendBuffered(data, contentType);
+    }
+    async pipeline(source, ...transforms) {
+        if (this.responseSent)
+            throw new Error("Response already sent");
+        this.responseSent = true;
+        const contentType = this.res.getHeader("Content-Type") ?? "application/octet-stream";
+        const encoding = shouldCompress(this.req, this.res, contentType, Infinity);
+        if (encoding) {
+            this.res.setHeader("Content-Encoding", encoding);
+            this.res.setHeader("Vary", "Accept-Encoding");
+        }
+        // HEAD requests: send headers only, no body
+        if (this.req.method === "HEAD") {
+            this.timing.markResponseStarted();
+            const finishedAt = process.hrtime.bigint();
+            this.res.setHeader("Server-Timing", this.timing.getBufferedHeaderValue(finishedAt));
+            this.res.writeHead(this.statusCode);
+            this.res.end();
+            return;
+        }
+        this.res.setHeader("Trailer", "Server-Timing");
+        this.timing.markResponseStarted();
+        this.onWriteHeadCallback?.();
+        this.res.writeHead(this.statusCode);
+        const compressStream = encoding ? createCompressStream(encoding) : null;
+        // Build pipeline stages
+        const stages = [...transforms];
+        if (compressStream)
+            stages.push(compressStream);
+        if (stages.length > 0) {
+            await pipeline(source, ...stages, this.res);
+        }
+        else {
+            await pipeline(source, this.res);
+        }
+        const finishedAt = process.hrtime.bigint();
+        this.res.addTrailers({ "Server-Timing": this.timing.getBufferedHeaderValue(finishedAt) });
+    }
+    empty() {
+        if (this.responseSent)
+            throw new Error("Response already sent");
+        this.responseSent = true;
+        this.timing.markResponseStarted();
+        const finishedAt = process.hrtime.bigint();
+        this.res.setHeader("Server-Timing", this.timing.getBufferedHeaderValue(finishedAt));
+        this.res.writeHead(this.statusCode);
+        this.res.end();
+    }
+    sendBuffered(body, contentType) {
+        if (this.responseSent)
+            throw new Error("Response already sent");
+        this.responseSent = true;
+        const etag = generateETag(body);
+        if (this.statusCode >= 200 && this.statusCode < 300 && isFresh(this.req, etag)) {
+            this.timing.markResponseStarted();
+            this.res.writeHead(304);
+            this.res.end();
+            return;
+        }
+        const encoding = shouldCompress(this.req, this.res, contentType, body.length);
+        let finalBody = body;
+        if (encoding) {
+            finalBody = compressSync(encoding, body);
+            this.res.setHeader("Content-Encoding", encoding);
+            this.res.setHeader("Vary", "Accept-Encoding");
+        }
+        this.res.setHeader("Content-Type", contentType);
+        this.res.setHeader("Content-Length", finalBody.length);
+        if (this.statusCode >= 200 && this.statusCode < 300) {
+            this.res.setHeader("ETag", etag);
+        }
+        this.timing.markResponseStarted();
+        const finishedAt = process.hrtime.bigint();
+        this.res.setHeader("Server-Timing", this.timing.getBufferedHeaderValue(finishedAt));
+        this.res.writeHead(this.statusCode);
+        if (this.req.method === "HEAD") {
+            this.res.end();
+        }
+        else {
+            this.res.end(finalBody);
+        }
+    }
+}

package/dist/router.d.mts

@@ -0,0 +1,13 @@
+import Router from "find-my-way";
+import type { Context } from "./context.mts";
+type RouterInstance = Router.Instance<Router.HTTPVersion.V1>;
+export type Handler = (ctx: Context) => Promise<void> | void;
+export interface RouteBuilder {
+    get(handler: Handler): RouteBuilder;
+    post(handler: Handler): RouteBuilder;
+    put(handler: Handler): RouteBuilder;
+    delete(handler: Handler): RouteBuilder;
+    patch(handler: Handler): RouteBuilder;
+}
+export declare function createRouteBuilder(router: RouterInstance, path: string): RouteBuilder;
+export {};

package/dist/router.mjs

@@ -0,0 +1,33 @@
+import Router from "find-my-way";
+export function createRouteBuilder(router, path) {
+    const builder = {
+        get(handler) {
+            router.on("GET", path, wrapHandler(handler));
+            router.on("HEAD", path, wrapHandler(handler));
+            return builder;
+        },
+        post(handler) {
+            router.on("POST", path, wrapHandler(handler));
+            return builder;
+        },
+        put(handler) {
+            router.on("PUT", path, wrapHandler(handler));
+            return builder;
+        },
+        delete(handler) {
+            router.on("DELETE", path, wrapHandler(handler));
+            return builder;
+        },
+        patch(handler) {
+            router.on("PATCH", path, wrapHandler(handler));
+            return builder;
+        },
+    };
+    return builder;
+}
+function wrapHandler(handler) {
+    return (_req, _res, _params, store) => {
+        const ctx = store;
+        return handler(ctx);
+    };
+}

package/dist/server-timing.d.mts

@@ -0,0 +1,7 @@
+export declare class ServerTiming {
+    private requestStart;
+    private responseStartedAt;
+    constructor();
+    markResponseStarted(): void;
+    getBufferedHeaderValue(responseFinishedAt: bigint): string;
+}

package/dist/server-timing.mjs

@@ -0,0 +1,17 @@
+export class ServerTiming {
+    requestStart;
+    responseStartedAt = null;
+    constructor() {
+        this.requestStart = process.hrtime.bigint();
+    }
+    markResponseStarted() {
+        this.responseStartedAt = process.hrtime.bigint();
+    }
+    getBufferedHeaderValue(responseFinishedAt) {
+        const now = responseFinishedAt;
+        const responseStarted = this.responseStartedAt ?? now;
+        const timeToResponseStarted = Number(responseStarted - this.requestStart) / 1_000_000;
+        const timeToResponseFinished = Number(now - responseStarted) / 1_000_000;
+        return `responseStarted;dur=${timeToResponseStarted.toFixed(3)}, responseFinished;dur=${timeToResponseFinished.toFixed(3)}`;
+    }
+}

package/dist/trusted-client-ip.d.mts

@@ -0,0 +1,20 @@
+export type HeaderRecord = Record<string, string | string[] | number | undefined>;
+export type HeaderGetter = {
+    get(name: string): string | null;
+};
+export type HeaderSource = HeaderGetter | HeaderRecord;
+export type RequestLike = {
+    headers: HeaderSource;
+};
+export type RemoteAddress = string | {
+    address?: string;
+    hostname?: string;
+    port?: number;
+};
+export interface TrustedClientIpOptions {
+    headers?: HeaderSource;
+    request?: RequestLike;
+    socketRemoteAddress?: string;
+    remoteAddress?: RemoteAddress;
+}
+export declare function resolveTrustedClientIp(options: TrustedClientIpOptions): string | undefined;

package/dist/trusted-client-ip.mjs

@@ -0,0 +1,57 @@
+function isHeaderGetter(headers) {
+    return typeof headers.get === "function";
+}
+function firstHeaderValue(value) {
+    const first = Array.isArray(value) ? value[0] : value;
+    return first === undefined ? undefined : String(first);
+}
+function headerRecordValue(headers, name) {
+    const direct = firstHeaderValue(headers[name]);
+    if (direct !== undefined)
+        return direct;
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === name)
+            return firstHeaderValue(value);
+    }
+    return undefined;
+}
+function headerValue(headers, name) {
+    if (!headers)
+        return undefined;
+    if (isHeaderGetter(headers))
+        return headers.get(name) ?? undefined;
+    return headerRecordValue(headers, name);
+}
+function withoutPort(value) {
+    if (value.startsWith("[")) {
+        const end = value.indexOf("]");
+        if (end > 0)
+            return value.slice(1, end);
+    }
+    const colon = value.lastIndexOf(":");
+    if (colon > -1 && value.indexOf(":") === colon && /^\d+$/.test(value.slice(colon + 1))) {
+        return value.slice(0, colon);
+    }
+    return value;
+}
+function normalizeIp(value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return undefined;
+    return withoutPort(trimmed);
+}
+function firstForwardedIp(value) {
+    return normalizeIp(value?.split(",")[0]);
+}
+function remoteAddressValue(value) {
+    if (typeof value === "string")
+        return normalizeIp(value);
+    return normalizeIp(value?.hostname ?? value?.address);
+}
+export function resolveTrustedClientIp(options) {
+    const headers = options.headers ?? options.request?.headers;
+    return (firstForwardedIp(headerValue(headers, "cf-connecting-ip")) ??
+        firstForwardedIp(headerValue(headers, "x-forwarded-for")) ??
+        remoteAddressValue(options.remoteAddress) ??
+        normalizeIp(options.socketRemoteAddress));
+}

package/dist/types.d.mts

@@ -0,0 +1,13 @@
+import type { LoggerOptions } from "./logger.mts";
+export interface CookieOptions {
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: "strict" | "lax" | "none" | true;
+    path?: string;
+    domain?: string;
+    expires?: Date;
+    maxAge?: number;
+}
+export interface ApplicationOptions {
+    logger?: LoggerOptions;
+}

package/dist/types.mjs

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@jongleberry/api-server",
+  "version": "1.0.0",
+  "description": "A Node.js HTTP server library",
+  "license": "MIT",
+  "author": "Jonathan Ong",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./trusted-client-ip": {
+      "types": "./dist/trusted-client-ip.d.mts",
+      "import": "./dist/trusted-client-ip.mjs"
+    }
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "dependencies": {
+    "bytes": "^3.1.2",
+    "compressible": "^2.0.18",
+    "cookie": "^1.1.1",
+    "find-my-way": "^9.6.0",
+    "http-assert": "^1.5.0",
+    "http-errors": "^2.0.1",
+    "negotiator": "^1.0.0",
+    "type-is": "^2.1.0"
+  },
+  "devDependencies": {
+    "@types/bytes": "^3.1.5",
+    "@types/compressible": "^2.0.3",
+    "@types/http-assert": "^1.5.6",
+    "@types/http-errors": "^2.0.5",
+    "@types/negotiator": "^0.6.4",
+    "@types/node": "^25.8.0",
+    "@types/supertest": "^7.2.0",
+    "@types/type-is": "^1.6.7",
+    "@vitest/coverage-v8": "^4.1.6",
+    "husky": "^9.1.7",
+    "oxfmt": "^0.50.0",
+    "oxlint": "^1.65.0",
+    "supertest": "^7.2.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepare": "node scripts/install-husky.mjs",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint src/ runtime-tests/",
+    "format": "oxfmt src/ runtime-tests/ docs/ README.md",
+    "format:check": "oxfmt --check src/ runtime-tests/ docs/ README.md",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage && node scripts/strip-lcov-branches.mjs",
+    "test:deno": "deno test --allow-net=127.0.0.1,localhost runtime-tests/trusted-client-ip.deno.test.mts",
+    "test:bun": "bun test runtime-tests/trusted-client-ip.bun.test.mts",
+    "test:runtimes": "npm run test:deno && npm run test:bun",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "http",
+    "server",
+    "node",
+    "api",
+    "express",
+    "koa",
+    "router"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jongleberry/api-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jongleberry/api-server/issues"
+  },
+  "homepage": "https://github.com/jongleberry/api-server"
+}