@vyriy/router 0.2.1 → 0.3.2

package/README.md

@@ -28,7 +28,7 @@ With Yarn:
 yarn add @vyriy/router
 ```
 
-## Usage
+## Basic Router
 
 ```ts
 import { createRouter } from '@vyriy/router';
@@ -36,7 +36,6 @@ import { createRouter } from '@vyriy/router';
 const router = createRouter();
 
 router.get('/health', async ({ event, query, headers, pathParameters, body }) => ({
-  statusCode: 200,
   body: JSON.stringify({
     ok: true,
     method: event.httpMethod,
@@ -46,6 +45,106 @@ router.get('/health', async ({ event, query, headers, pathParameters, body }) =>
     body,
   }),
 }));
+
+router.fallback(async ({ event }) => ({
+  statusCode: 404,
+  body: JSON.stringify({
+    message: 'Not Found',
+    path: event.path,
+  }),
+}));
+
+export const handler = (event: Parameters<typeof router.route>[0]) => router.route(event);
+```
+
+## Stream Router
+
+Use `createStreamRouter()` when handlers write directly to a Lambda response stream. The stream is passed as the second handler argument, and stream handlers do not return a response object.
+
+```ts
+import { createStreamRouter } from '@vyriy/router';
+
+const streamRouter = createStreamRouter();
+
+streamRouter.get('/events', ({ event, query }, responseStream) => {
+  responseStream.setContentType?.('text/plain');
+  responseStream.write(`path: ${event.path}\n`);
+  responseStream.write(`cursor: ${query?.cursor ?? 'start'}\n`);
+  responseStream.end('done');
+});
+
+streamRouter.fallback(({ event }, responseStream) => {
+  responseStream.setContentType?.('application/json');
+  responseStream.end(
+    JSON.stringify({
+      message: 'Not Found',
+      path: event.path,
+    }),
+  );
+});
+
+export const handler = (
+  event: Parameters<typeof streamRouter.route>[0],
+  responseStream: Parameters<typeof streamRouter.route>[1],
+) => streamRouter.route(event, responseStream);
+```
+
+## Calm Composition
+
+The router keeps request matching separate from handler wrappers and local server adapters. A small API can stay as a plain composition of focused packages:
+
+```ts
+import { api } from '@vyriy/handler';
+import { createRouter } from '@vyriy/router';
+import { server } from '@vyriy/server';
+
+const router = createRouter();
+
+router.get('/health', () => ({
+  body: JSON.stringify({
+    ok: true,
+  }),
+}));
+
+const handler = api((event) => router.route(event));
+
+server(handler);
+```
+
+The same shape works for Lambda response streaming:
+
+```ts
+import { streamApi } from '@vyriy/handler';
+import { createStreamRouter } from '@vyriy/router';
+import { streamServer } from '@vyriy/server';
+
+const router = createStreamRouter();
+
+router.get('/events', (_params, responseStream) => {
+  responseStream.setContentType?.('text/plain');
+  responseStream.end('ok');
+});
+
+const handler = streamApi((event, responseStream) => router.route(event, responseStream));
+
+streamServer(handler);
+```
+
+For a Lambda-only entrypoint, keep the same composition and export the handler:
+
+```ts
+import { api } from '@vyriy/handler';
+import { createRouter } from '@vyriy/router';
+
+const router = createRouter();
+
+router.get('/health', () => ({
+  body: JSON.stringify({
+    ok: true,
+  }),
+}));
+
+export const handler = api((event) => router.route(event));
 ```
 
 ## Exports
@@ -53,24 +152,33 @@ router.get('/health', async ({ event, query, headers, pathParameters, body }) =>
 The package exposes both the root entry and the direct module entry:
 
 ```ts
-import { createRouter } from '@vyriy/router';
-import { Router } from '@vyriy/router/router';
+import { createRouter, createStreamRouter } from '@vyriy/router';
+import { Router, StreamRouter } from '@vyriy/router/router';
 ```
 
 ## API
 
 - `createRouter()` returns a chainable router API.
+- `createStreamRouter()` returns a chainable response streaming router API.
 - `router.get(path, handler)` registers a `GET` handler.
 - `router.post(path, handler)` registers a `POST` handler.
 - `router.put(path, handler)` registers a `PUT` handler.
 - `router.delete(path, handler)` registers a `DELETE` handler.
 - `router.patch(path, handler)` registers a `PATCH` handler.
+- `router.fallback(handler)` registers a handler for unmatched requests.
 - `router.route(event)` resolves the matching route and returns an API Gateway response.
+- `streamRouter.route(event, responseStream)` resolves the matching route and writes to the stream.
+
+Route handlers may omit `statusCode`; the router normalizes missing status codes to `200` before returning from `router.route(event)`.
 
-The low-level `Router` class is also available from `@vyriy/router/router` and exposes only:
+The low-level `Router` and `StreamRouter` classes are also available from `@vyriy/router/router`:
 
 - `router.on(method, path, handler)`
+- `router.fallback(handler)`
 - `router.route(event)`
+- `streamRouter.on(method, path, handler)`
+- `streamRouter.fallback(handler)`
+- `streamRouter.route(event, responseStream)`
 
 Route handlers receive:
 
@@ -83,3 +191,9 @@ type HandlerParams = {
   event: APIGatewayProxyEvent;
 };
 ```
+
+Stream route handlers receive the same `HandlerParams` as the first argument and `ResponseStream` as the second argument:
+
+```ts
+type StreamHandler = (params: HandlerParams, responseStream: ResponseStream) => void | Promise<void>;
+```

package/create.d.ts

@@ -1,2 +1,3 @@
-import type { RouterApi } from './types.js';
+import type { RouterApi, StreamRouterApi } from './types.js';
 export declare const createRouter: () => RouterApi;
+export declare const createStreamRouter: () => StreamRouterApi;

package/create.js

@@ -1,4 +1,4 @@
-import { Router } from './router.js';
+import { Router, StreamRouter } from './router.js';
 export const createRouter = () => {
     const router = new Router();
     const api = {
@@ -18,6 +18,10 @@ export const createRouter = () => {
             router.on('DELETE', path, handler);
             return api;
         },
+        fallback(handler) {
+            router.fallback(handler);
+            return api;
+        },
         patch(path, handler) {
             router.on('PATCH', path, handler);
             return api;
@@ -28,3 +32,36 @@ export const createRouter = () => {
     };
     return api;
 };
+export const createStreamRouter = () => {
+    const router = new StreamRouter();
+    const api = {
+        get(path, handler) {
+            router.on('GET', path, handler);
+            return api;
+        },
+        post(path, handler) {
+            router.on('POST', path, handler);
+            return api;
+        },
+        put(path, handler) {
+            router.on('PUT', path, handler);
+            return api;
+        },
+        delete(path, handler) {
+            router.on('DELETE', path, handler);
+            return api;
+        },
+        fallback(handler) {
+            router.fallback(handler);
+            return api;
+        },
+        patch(path, handler) {
+            router.on('PATCH', path, handler);
+            return api;
+        },
+        route(event, responseStream) {
+            return router.route(event, responseStream);
+        },
+    };
+    return api;
+};

package/index.d.ts

@@ -1,2 +1,3 @@
 export * from './create.js';
+export * from './router.js';
 export type * from './types.js';

package/index.js

@@ -1 +1,2 @@
 export * from './create.js';
+export * from './router.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vyriy/router",
-  "version": "0.2.1",
+  "version": "0.3.2",
   "description": "Router utility for Vyriy projects",
   "type": "module",
   "main": "./index.js",

package/router.d.ts

@@ -1,6 +1,14 @@
-import type { APIGatewayProxyEvent, APIGatewayProxyResult, Handler } from './types.js';
-export declare class Router {
-    private readonly routes;
-    on(method: string, path: string, handler: Handler): this;
-    route(event: APIGatewayProxyEvent): Promise<APIGatewayProxyResult>;
+import type { APIGatewayProxyEvent, Handler, ResponseStream, RouteResult, StreamHandler } from './types.js';
+declare class BaseRouter<CurrentHandler> {
+    protected fallbackHandler?: CurrentHandler;
+    protected readonly routes: Record<string, Record<string, CurrentHandler>>;
+    on(method: string, path: string, handler: CurrentHandler): this;
+    fallback(handler: CurrentHandler): this;
 }
+export declare class Router extends BaseRouter<Handler> {
+    route(event: APIGatewayProxyEvent): Promise<RouteResult>;
+}
+export declare class StreamRouter extends BaseRouter<StreamHandler> {
+    route(event: APIGatewayProxyEvent, responseStream: ResponseStream): Promise<void>;
+}
+export {};

package/router.js

@@ -1,39 +1,94 @@
 import { METHODS, STATUS_CODES } from 'node:http';
 const SUPPORTED_METHODS = new Set(METHODS.map((method) => method.toUpperCase()));
-export class Router {
+const normalizeResult = (result) => ({
+    statusCode: result.statusCode ?? 200,
+    body: result.body,
+    headers: result.headers,
+    isBase64Encoded: result.isBase64Encoded,
+    multiValueHeaders: result.multiValueHeaders,
+});
+const registerRoute = (routes, method, path, handler) => {
+    const normalizedMethod = method.toUpperCase();
+    if (!SUPPORTED_METHODS.has(normalizedMethod)) {
+        throw new Error(`Unsupported HTTP method: ${normalizedMethod}`);
+    }
+    const routeGroup = (routes[normalizedMethod] ??= {});
+    if (routeGroup[path]) {
+        throw new Error(`${normalizedMethod} ${path} already exists!`);
+    }
+    routeGroup[path] = handler;
+};
+class BaseRouter {
+    fallbackHandler;
     routes = {};
     on(method, path, handler) {
-        const normalizedMethod = method.toUpperCase();
-        if (!SUPPORTED_METHODS.has(normalizedMethod)) {
-            throw new Error(`Unsupported HTTP method: ${normalizedMethod}`);
-        }
-        const routeGroup = (this.routes[normalizedMethod] ??= {});
-        if (routeGroup[path]) {
-            throw new Error(`${normalizedMethod} ${path} already exists!`);
-        }
-        routeGroup[path] = handler;
+        registerRoute(this.routes, method, path, handler);
         return this;
     }
+    fallback(handler) {
+        this.fallbackHandler = handler;
+        return this;
+    }
+}
+export class Router extends BaseRouter {
     async route(event) {
         const { httpMethod, path, queryStringParameters, body, headers, pathParameters } = event;
-        const result = await this.routes[httpMethod]?.[path]?.({
-            query: queryStringParameters ?? undefined,
-            body: body ?? undefined,
-            headers,
-            pathParameters: pathParameters ?? undefined,
-            event,
-        });
-        return result
-            ? {
-                statusCode: result.statusCode ?? 200,
-                body: result.body,
-                headers: result.headers,
-            }
-            : {
-                statusCode: 404,
-                body: JSON.stringify({
-                    message: STATUS_CODES[404],
-                }),
-            };
+        const exactHandler = this.routes[httpMethod]?.[path];
+        if (exactHandler) {
+            const result = await exactHandler({
+                query: queryStringParameters ?? undefined,
+                body: body ?? undefined,
+                headers,
+                pathParameters: pathParameters ?? undefined,
+                event,
+            });
+            return normalizeResult(result);
+        }
+        if (this.fallbackHandler) {
+            const fallbackResult = await this.fallbackHandler({
+                query: queryStringParameters ?? undefined,
+                body: body ?? undefined,
+                headers,
+                pathParameters: pathParameters ?? undefined,
+                event,
+            });
+            return normalizeResult(fallbackResult);
+        }
+        return {
+            statusCode: 404,
+            body: JSON.stringify({
+                message: STATUS_CODES[404],
+            }),
+        };
+    }
+}
+export class StreamRouter extends BaseRouter {
+    async route(event, responseStream) {
+        const { httpMethod, path, queryStringParameters, body, headers, pathParameters } = event;
+        const exactHandler = this.routes[httpMethod]?.[path];
+        if (exactHandler) {
+            await exactHandler({
+                query: queryStringParameters ?? undefined,
+                body: body ?? undefined,
+                headers,
+                pathParameters: pathParameters ?? undefined,
+                event,
+            }, responseStream);
+            return;
+        }
+        if (this.fallbackHandler) {
+            await this.fallbackHandler({
+                query: queryStringParameters ?? undefined,
+                body: body ?? undefined,
+                headers,
+                pathParameters: pathParameters ?? undefined,
+                event,
+            }, responseStream);
+            return;
+        }
+        responseStream.setContentType?.('application/json');
+        responseStream.end(JSON.stringify({
+            message: STATUS_CODES[404],
+        }));
     }
 }

package/types.d.ts

@@ -1,10 +1,23 @@
 import type { APIGatewayProxyEvent, APIGatewayProxyEventQueryStringParameters, APIGatewayProxyResult } from 'aws-lambda';
 export type { APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda';
-export type Result = {
+type MaybePromise<Result> = Result | Promise<Result>;
+export type RouteResult = APIGatewayProxyResult;
+export type RouteHandlerResult = {
     body: APIGatewayProxyResult['body'];
     headers?: APIGatewayProxyResult['headers'];
+    isBase64Encoded?: APIGatewayProxyResult['isBase64Encoded'];
+    multiValueHeaders?: APIGatewayProxyResult['multiValueHeaders'];
     statusCode?: APIGatewayProxyResult['statusCode'];
 };
+export type ResponseStream = {
+    end: {
+        (): unknown;
+        (chunk: string | Buffer | Uint8Array): unknown;
+    };
+    setContentType?: (contentType: string) => unknown;
+    writableEnded?: boolean;
+    write(chunk: string | Buffer | Uint8Array): unknown;
+};
 export type HandlerParams = {
     query?: APIGatewayProxyEventQueryStringParameters;
     body?: string;
@@ -12,12 +25,23 @@ export type HandlerParams = {
     pathParameters?: APIGatewayProxyEvent['pathParameters'];
     event: APIGatewayProxyEvent;
 };
-export type Handler = (params: HandlerParams) => Promise<Result | undefined>;
+export type Handler = (params: HandlerParams) => MaybePromise<RouteHandlerResult>;
+export type StreamHandler = (params: HandlerParams, responseStream: ResponseStream) => MaybePromise<void>;
 export type RouterApi = {
     get(path: string, handler: Handler): RouterApi;
     post(path: string, handler: Handler): RouterApi;
     put(path: string, handler: Handler): RouterApi;
     delete(path: string, handler: Handler): RouterApi;
+    fallback(handler: Handler): RouterApi;
     patch(path: string, handler: Handler): RouterApi;
-    route(event: APIGatewayProxyEvent): Promise<APIGatewayProxyResult>;
+    route(event: APIGatewayProxyEvent): Promise<RouteResult>;
+};
+export type StreamRouterApi = {
+    get(path: string, handler: StreamHandler): StreamRouterApi;
+    post(path: string, handler: StreamHandler): StreamRouterApi;
+    put(path: string, handler: StreamHandler): StreamRouterApi;
+    delete(path: string, handler: StreamHandler): StreamRouterApi;
+    fallback(handler: StreamHandler): StreamRouterApi;
+    patch(path: string, handler: StreamHandler): StreamRouterApi;
+    route(event: APIGatewayProxyEvent, responseStream: ResponseStream): Promise<void>;
 };