@sourceregistry/node-webserver 1.7.4 → 1.7.6

package/README.md

@@ -1,21 +1,37 @@
+<div align="center">
+
 # @sourceregistry/node-webserver
 
-[![npm version](https://img.shields.io/npm/v/%40sourceregistry%2Fnode-webserver?logo=npm)](https://www.npmjs.com/package/@sourceregistry/node-webserver)
-[![JSR](https://jsr.io/badges/@sourceregistry/node-webserver)](https://jsr.io/@sourceregistry/node-webserver)
-[![License](https://img.shields.io/npm/l/%40sourceregistry%2Fnode-webserver)](./LICENSE)
-[![CI](https://github.com/SourceRegistry/node-webserver/actions/workflows/ci.yml/badge.svg)](https://github.com/SourceRegistry/node-webserver/actions/workflows/ci.yml)
+**TypeScript web server for Node.js built on the web-standard `Request` and `Response` APIs**
+
+[![npm version](https://img.shields.io/npm/v/@sourceregistry/node-webserver?style=flat-square&color=f96743)](https://www.npmjs.com/package/@sourceregistry/node-webserver)
+[![npm downloads](https://img.shields.io/npm/dm/@sourceregistry/node-webserver?style=flat-square)](https://www.npmjs.com/package/@sourceregistry/node-webserver)
+[![JSR](https://jsr.io/badges/@sourceregistry/node-webserver?style=flat-square)](https://jsr.io/@sourceregistry/node-webserver)
+[![license](https://img.shields.io/npm/l/@sourceregistry/node-webserver?style=flat-square)](./LICENSE)
+[![node](https://img.shields.io/node/v/@sourceregistry/node-webserver?style=flat-square&color=339933&logo=node.js&logoColor=white)](https://nodejs.org)
+[![CI](https://img.shields.io/github/actions/workflow/status/SourceRegistry/node-webserver/ci.yml?style=flat-square&label=CI)](https://github.com/SourceRegistry/node-webserver/actions/workflows/ci.yml)
+[![issues](https://img.shields.io/github/issues/SourceRegistry/node-webserver?style=flat-square)](https://github.com/SourceRegistry/node-webserver/issues)
+
+Typed router · Middleware · Route enhancers · WebSockets · SSE · Static files · CORS · Rate limiting · Security headers
+
+[Docs](https://sourceregistry.github.io/node-webserver/) · [npm](https://www.npmjs.com/package/@sourceregistry/node-webserver) · [JSR](https://jsr.io/@sourceregistry/node-webserver) · [Issues](https://github.com/SourceRegistry/node-webserver/issues)
 
-TypeScript web server for Node.js built around the web platform `Request` and `Response` APIs.
+</div>
 
-It provides:
+---
 
-- A typed router with path params
-- Middleware support
+## Features
+
+- Typed router with path params and nested routers
+- Middleware with short-circuit support
 - Route enhancers for typed request-scoped context
-- Router lifecycle hooks with `pre()` and `post()`
-- WebSocket routing
+- Router lifecycle hooks — `pre()` and `post()`
+- WebSocket routing with enhancer support
+- Server-Sent Events via `sse()`
 - Cookie helpers
-- Built-in middleware for CORS, rate limiting, security headers, request IDs, and timeouts
+- Static file serving with path traversal protection
+- Built-in middleware: CORS, rate limiting, security headers, request IDs, timeouts
+- HTTPS support
 - Safer defaults for host handling and WebSocket upgrade validation
 
 ## Installation
@@ -34,16 +50,54 @@ import { WebServer, json, text } from "@sourceregistry/node-webserver";
 const app = new WebServer();
 
 app.GET("/", () => text("hello world"));
+app.GET("/health", () => json({ ok: true }));
 
-app.GET("/health", () => json({
-  ok: true
-}));
+app.listen(3000, () => console.log("listening on http://127.0.0.1:3000"));
+```
+
+## Overview
 
-app.listen(3000, () => {
-  console.log("listening on http://127.0.0.1:3000");
+```ts
+import {
+  WebServer, Router, enhance, json, text, html, sse,
+  CORS, RateLimiter, RequestId, Security, Timeout,
+  error, redirect
+} from "@sourceregistry/node-webserver";
+
+const app = new WebServer({
+  locals: (event) => ({ requestId: crypto.randomUUID() }),
+  security: { trustedProxies: ["127.0.0.1"], maxRequestBodySize: 1024 * 1024 }
 });
+
+// Built-in middleware
+app.useMiddleware(RequestId.assign());
+app.useMiddleware(Security.headers());
+app.useMiddleware(CORS.policy({ origin: ["https://app.example.com"], credentials: true }));
+app.useMiddleware(RateLimiter.slidingWindowLimit({ windowMs: 60_000, max: 100 }));
+app.useMiddleware(Timeout.deadline({ ms: 5000 }));
+
+// Typed route enhancers
+const withAuth = async (event) => {
+  const token = event.request.headers.get("authorization");
+  if (!token) error(401, { message: "Unauthorized" });
+  return { user: await verifyToken(token) };
+};
+
+app.GET("/me", enhance(
+  async (event) => json(event.context.user),
+  withAuth,
+));
+
+// Nested routers
+const api = new Router();
+api.GET("/status", () => json({ ok: true }));
+app.use("/api", api);
+
+app.listen(3000);
 ```
 
+---
+
 ## Core Concepts
 
 ### Create a server
@@ -413,6 +467,45 @@ app.GET("/admin", enhance(
 ));
 ```
 
+### Typed enhancers
+
+You can define reusable enhancers with the `EventEnhancer` type. The fifth type parameter (`TExtra`) controls whether the enhancer receives extra event properties like `websocket`.
+
+Without WebSocket — works in any HTTP route:
+
+```ts
+import type { EventEnhancer } from "@sourceregistry/node-webserver";
+
+const withAuth: EventEnhancer<any, any, App.Locals, { user: { id: string; role: string } }> = async (event) => {
+  const token = event.request.headers.get("authorization");
+  if (!token) error(401, { message: "Unauthorized" });
+  return { user: await verifyToken(token) };
+};
+```
+
+With WebSocket — only usable in `router.WS()` routes:
+
+```ts
+import type { EventEnhancer } from "@sourceregistry/node-webserver";
+import type { WebSocket } from "ws";
+
+const withWsAuth: EventEnhancer<any, any, App.Locals, { user: { id: string } }, { websocket: WebSocket }> = async (event) => {
+  // event.websocket is available here
+  const token = event.request.headers.get("authorization");
+  if (!token) error(401, { message: "Unauthorized" });
+  return { user: await verifyToken(token) };
+};
+
+router.WS("/ws/chat", enhance(
+  async ({ context, websocket }) => {
+    websocket.send(`hello ${context.user.id}`);
+  },
+  withWsAuth
+));
+```
+
+Plain HTTP enhancers (`TExtra = {}`) can still be passed to a WS `enhance()` call — they just won't have access to `websocket`.
+
 ## Router Lifecycle Hooks
 
 Use `pre()` for logic that should run before route resolution, and `post()` for logic that should run after a response has been produced.
@@ -486,6 +579,32 @@ app.WS("/ws/chat/[room]", async (event) => {
 });
 ```
 
+`enhance()` works with WebSocket handlers too. When your handler includes `websocket` in the event type, the returned function requires it automatically:
+
+```ts
+import { enhance, error } from "@sourceregistry/node-webserver";
+
+app.WS("/ws/chat/[room]", enhance(
+  async ({ context, params, websocket }) => {
+    websocket.send(`joined:${params.room} as ${context.user.id}`);
+
+    websocket.on("message", (message) => {
+      websocket.send(`echo:${message.toString()}`);
+    });
+  },
+  async (event) => {
+    const token = event.request.headers.get("authorization");
+    if (!token) {
+      error(401, { message: "Unauthorized" });
+    }
+
+    return { user: { id: "u_1", role: "member" } };
+  }
+));
+```
+
+If an enhancer returns a `Response` (or throws via `error()`), the WebSocket handler is skipped and the connection closes.
+
 ## Static Files
 
 Use `dir()` to expose a directory through a route, or `serveStatic()` directly if you want manual control.
@@ -657,13 +776,20 @@ For a production-oriented baseline with:
 
 see [examples/public-baseline.ts](./examples/public-baseline.ts).
 
+---
+
 ## Development
 
 ```bash
-npm test
+npm test            # run tests
+npm run test:ui     # vitest UI
+npm run test:coverage
 npm run build
+npm run docs:build  # generate TypeDoc
 ```
 
+---
+
 ## License
 
-Apache-2.0. See [LICENSE](./LICENSE).
+[Apache-2.0](./LICENSE) © [Alexander Slaa](https://github.com/SourceRegistry)

package/dist/enhance.d.ts

@@ -3,7 +3,7 @@ import { MaybePromise } from './types/MaybePromise';
 import { WebSocket } from 'ws';
 type AnyFn = (...args: any[]) => any;
 type ConcatReturnTypes<T extends AnyFn[]> = T extends [] ? {} : T extends [infer First, ...infer Rest] ? First extends AnyFn ? Awaited<ReturnType<First>> & ConcatReturnTypes<Rest extends AnyFn[] ? Rest : []> : {} : {};
-export type EventEnhancer<Params extends Partial<Record<string, string>> = Partial<Record<string, string>>, RouteId extends string | null = string | null, Locals extends App.Locals = App.Locals, Context extends Record<string, any> = Record<string, any>> = (event: RequestEvent<Params, RouteId, Locals>) => MaybePromise<Context | void | undefined | Response>;
+export type EventEnhancer<Params extends Partial<Record<string, string>> = Partial<Record<string, string>>, RouteId extends string | null = string | null, Locals extends App.Locals = App.Locals, Context extends Record<string, any> = Record<string, any>, TExtra extends object = {}> = (event: RequestEvent<Params, RouteId, Locals> & TExtra) => MaybePromise<Context | void | undefined | Response>;
 export type EnhancedRequestEvent<Params extends Partial<Record<string, string>> = Partial<Record<string, string>>, RouteId extends string | null = string | null, Locals extends App.Locals = App.Locals, Context extends Record<string, any> = Record<string, any>> = RequestEvent<Params, RouteId, Locals> & {
     context: Context;
 };
@@ -11,5 +11,5 @@ export type EnhancedRouteHandler<Params extends Partial<Record<string, string>>
 export type EnhancedWebSocketHandler<Params extends Partial<Record<string, string>> = Partial<Record<string, string>>, RouteId extends string | null = string | null, Locals extends App.Locals = App.Locals, Context extends Record<string, any> = Record<string, any>> = (event: EnhancedRequestEvent<Params, RouteId, Locals, Context> & {
     websocket: WebSocket;
 }) => MaybePromise<any>;
-export declare const enhance: <Params extends Partial<Record<string, string>> = Partial<Record<string, string>>, RouteId extends string | null = string | null, Locals extends App.Locals = App.Locals, Enhancers extends EventEnhancer<Params, RouteId, Locals, any>[] = EventEnhancer<Params, RouteId, Locals, any>[], Context extends Awaited<ConcatReturnTypes<Enhancers>> = Awaited<ConcatReturnTypes<Enhancers>>, TExtra extends object = {}, TReturn = unknown>(handler: (event: EnhancedRequestEvent<Params, RouteId, Locals, Context> & TExtra) => MaybePromise<TReturn>, ...enhancers: Enhancers) => (event: RequestEvent<Params, RouteId, Locals> & TExtra) => Promise<TReturn | Response>;
+export declare const enhance: <Params extends Partial<Record<string, string>> = Partial<Record<string, string>>, RouteId extends string | null = string | null, Locals extends App.Locals = App.Locals, TExtra extends object = {}, TReturn = unknown, Enhancers extends EventEnhancer<Params, RouteId, Locals, any, TExtra>[] = EventEnhancer<Params, RouteId, Locals, any, TExtra>[], Context extends Awaited<ConcatReturnTypes<Enhancers>> = Awaited<ConcatReturnTypes<Enhancers>>>(handler: (event: EnhancedRequestEvent<Params, RouteId, Locals, Context> & TExtra) => MaybePromise<TReturn>, ...enhancers: Enhancers) => (event: RequestEvent<Params, RouteId, Locals> & TExtra) => Promise<TReturn | Response>;
 export {};