@sourceregistry/node-webserver 1.7.3 → 1.7.5

package/README.md

@@ -413,6 +413,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 +525,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.

package/dist/enhance.d.ts

@@ -1,11 +1,15 @@
 import { RequestEvent } from './types';
 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;
 };
 export type EnhancedRouteHandler<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>) => MaybePromise<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, Enhancers extends EventEnhancer<Params, RouteId, Locals, any>[] = EventEnhancer<Params, RouteId, Locals, any>[], Context extends Awaited<ConcatReturnTypes<Enhancers>> = Awaited<ConcatReturnTypes<Enhancers>>>(handler: EnhancedRouteHandler<Params, RouteId, Locals, Context>, ...enhancers: Enhancers) => (event: RequestEvent<Params, RouteId, Locals>) => Promise<Response>;
+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, 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 {};