@vyriy/router 0.2.1 → 0.3.0

package/README.md

@@ -9,6 +9,7 @@ This package provides a small API Gateway router for Lambda handlers.
 It is intentionally kept small:
 
 - matches by HTTP method and exact path
+- supports simple prefix dispatch for handler factories such as static file serving
 - passes API Gateway event data into handlers
 - returns a Lambda-friendly response shape
 
@@ -32,6 +33,7 @@ yarn add @vyriy/router
 
 ```ts
 import { createRouter } from '@vyriy/router';
+import { staticFiles } from '@vyriy/server/static';
 
 const router = createRouter();
 
@@ -46,6 +48,26 @@ router.get('/health', async ({ event, query, headers, pathParameters, body }) =>
     body,
   }),
 }));
+
+router.prefix('/static', staticFiles('./public'));
+
+router.fallback(async ({ event }) => ({
+  statusCode: 404,
+  body: JSON.stringify({
+    message: 'Not Found',
+    path: event.path,
+  }),
+}));
+```
+
+Prefix handlers receive the relative matched path in `pathParameters.proxy`, so they can behave like normal handlers:
+
+```ts
+router.prefix('/events', async ({ pathParameters, responseStream }) => {
+  responseStream?.setContentType?.('text/plain');
+  responseStream?.write(`Path: ${pathParameters?.proxy}`);
+  responseStream?.end();
+});
 ```
 
 ## Exports
@@ -65,11 +87,15 @@ import { Router } from '@vyriy/router/router';
 - `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.prefix(pathPrefix, handler)` registers a handler for every request under a URL prefix.
+- `router.fallback(handler)` registers a handler for unmatched requests.
 - `router.route(event)` resolves the matching route and returns an API Gateway response.
 
 The low-level `Router` class is also available from `@vyriy/router/router` and exposes only:
 
 - `router.on(method, path, handler)`
+- `router.prefix(pathPrefix, handler)`
+- `router.fallback(handler)`
 - `router.route(event)`
 
 Route handlers receive:
@@ -80,6 +106,7 @@ type HandlerParams = {
   body?: string;
   headers?: APIGatewayProxyEvent['headers'];
   pathParameters?: APIGatewayProxyEvent['pathParameters'];
+  responseStream?: ResponseStream;
   event: APIGatewayProxyEvent;
 };
 ```

package/create.js

@@ -18,10 +18,18 @@ 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;
         },
+        prefix(pathPrefix, handler) {
+            router.prefix(pathPrefix, handler);
+            return api;
+        },
         route(event) {
             return router.route(event);
         },

package/package.json

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

package/router.d.ts

@@ -1,6 +1,10 @@
-import type { APIGatewayProxyEvent, APIGatewayProxyResult, Handler } from './types.js';
+import type { APIGatewayProxyEvent, Handler, ResponseStream, RouteResult } from './types.js';
 export declare class Router {
+    private fallbackHandler?;
     private readonly routes;
+    private readonly staticRoutes;
     on(method: string, path: string, handler: Handler): this;
-    route(event: APIGatewayProxyEvent): Promise<APIGatewayProxyResult>;
+    fallback(handler: Handler): this;
+    prefix(pathPrefix: string, handler: Handler): this;
+    route(event: APIGatewayProxyEvent, responseStream?: ResponseStream): Promise<RouteResult | void>;
 }

package/router.js

@@ -1,7 +1,36 @@
 import { METHODS, STATUS_CODES } from 'node:http';
 const SUPPORTED_METHODS = new Set(METHODS.map((method) => method.toUpperCase()));
+const removeLeadingSlashes = (value) => {
+    let start = 0;
+    while (value[start] === '/') {
+        start += 1;
+    }
+    return value.slice(start);
+};
+const removeTrailingSlashes = (value) => {
+    let end = value.length;
+    while (end > 0 && value[end - 1] === '/') {
+        end -= 1;
+    }
+    return value.slice(0, end);
+};
+const getPrefixPath = (eventPath, route) => {
+    if (eventPath !== route.pathPrefix && !eventPath.startsWith(`${route.pathPrefix}/`)) {
+        return undefined;
+    }
+    return decodeURIComponent(removeLeadingSlashes(eventPath.slice(route.pathPrefix.length)));
+};
+const normalizeResult = (result) => ({
+    statusCode: result.statusCode ?? 200,
+    body: result.body,
+    headers: result.headers,
+    isBase64Encoded: result.isBase64Encoded,
+    multiValueHeaders: result.multiValueHeaders,
+});
 export class Router {
+    fallbackHandler;
     routes = {};
+    staticRoutes = [];
     on(method, path, handler) {
         const normalizedMethod = method.toUpperCase();
         if (!SUPPORTED_METHODS.has(normalizedMethod)) {
@@ -14,26 +43,67 @@ export class Router {
         routeGroup[path] = handler;
         return this;
     }
-    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,
+    fallback(handler) {
+        this.fallbackHandler = handler;
+        return this;
+    }
+    prefix(pathPrefix, handler) {
+        this.staticRoutes.push({
+            handler,
+            pathPrefix: removeTrailingSlashes(pathPrefix) || '/',
         });
-        return result
-            ? {
-                statusCode: result.statusCode ?? 200,
-                body: result.body,
-                headers: result.headers,
+        return this;
+    }
+    async route(event, responseStream) {
+        const { httpMethod, path, queryStringParameters, body, headers, pathParameters } = event;
+        const exactHandler = this.routes[httpMethod]?.[path];
+        if (exactHandler) {
+            const result = await exactHandler({
+                query: queryStringParameters ?? undefined,
+                body: body ?? undefined,
+                headers,
+                pathParameters: pathParameters ?? undefined,
+                responseStream,
+                event,
+            });
+            return result ? normalizeResult(result) : undefined;
+        }
+        for (const staticRoute of this.staticRoutes) {
+            const proxy = getPrefixPath(path, staticRoute);
+            if (proxy !== undefined) {
+                const prefixResult = await staticRoute.handler({
+                    query: queryStringParameters ?? undefined,
+                    body: body ?? undefined,
+                    headers,
+                    pathParameters: {
+                        ...pathParameters,
+                        proxy,
+                    },
+                    responseStream,
+                    event,
+                });
+                if (prefixResult) {
+                    return normalizeResult(prefixResult);
+                }
+                return undefined;
             }
-            : {
-                statusCode: 404,
-                body: JSON.stringify({
-                    message: STATUS_CODES[404],
-                }),
-            };
+        }
+        if (this.fallbackHandler) {
+            const fallbackResult = await this.fallbackHandler({
+                query: queryStringParameters ?? undefined,
+                body: body ?? undefined,
+                headers,
+                pathParameters: pathParameters ?? undefined,
+                responseStream,
+                event,
+            });
+            return fallbackResult ? normalizeResult(fallbackResult) : undefined;
+        }
+        return {
+            statusCode: 404,
+            body: JSON.stringify({
+                message: STATUS_CODES[404],
+            }),
+        };
     }
 }

package/types.d.ts

@@ -1,23 +1,37 @@
 import type { APIGatewayProxyEvent, APIGatewayProxyEventQueryStringParameters, APIGatewayProxyResult } from 'aws-lambda';
 export type { APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda';
-export type Result = {
+export type RouteResult = {
     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;
     headers?: APIGatewayProxyEvent['headers'];
     pathParameters?: APIGatewayProxyEvent['pathParameters'];
+    responseStream?: ResponseStream;
     event: APIGatewayProxyEvent;
 };
-export type Handler = (params: HandlerParams) => Promise<Result | undefined>;
+export type Handler = (params: HandlerParams) => Promise<RouteResult | 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>;
+    prefix(pathPrefix: string, handler: Handler): RouterApi;
+    route(event: APIGatewayProxyEvent, responseStream?: ResponseStream): Promise<RouteResult | void>;
 };