@vyriy/router 0.2.0 → 0.3.0

package/AGENTS.md

@@ -0,0 +1,65 @@
+# Vyriy Package Agent Guide
+
+This package belongs to the Vyriy toolkit. Keep changes calm, explicit, reusable, and easy to reason about.
+
+## Architecture
+
+- Prefer simple modules over clever frameworks or hidden conventions.
+- Keep package boundaries explicit and avoid project-specific coupling.
+- Extract only proven reusable behavior.
+- Keep public APIs small, typed, documented, and stable.
+- Prefer SSR-friendly and SSG-friendly code paths.
+- Keep integrations replaceable and avoid hard coupling to a CMS or runtime host.
+- Prefer AWS serverless-compatible assumptions when infrastructure concerns appear.
+
+## File Shape
+
+- Prefer one exported runtime method, component, or helper per production file when it stays readable.
+- Prefer one matching test file per production file, for example `feature.ts` and `feature.test.ts`.
+- Use focused folders when behavior naturally splits into several related files.
+- Keep `index.ts` as a public re-export surface only. Do not place implementation logic in it.
+- Use `.js` relative import and export specifiers in TypeScript source where package style requires it.
+- Add `types.ts` when public shared types are part of the package contract.
+- Keep constants near the code that owns them unless they are shared or clarify repeated behavior.
+
+## Public Surface
+
+- Every new public export should be re-exported from `index.ts`.
+- Add or update `index.test.ts` when the public export surface changes.
+- Add JSDoc for public exports when behavior, parameters, return values, or usage expectations need explanation.
+- Do not hand-maintain source package `exports` maps unless the package has a real custom publishing need.
+
+## Tests
+
+- Tests use Jest and `@jest/globals`.
+- Cover public behavior and meaningful edge cases.
+- Prefer behavior-focused tests over private implementation lock-in.
+- When mocking modules, install mocks before loading the module under test.
+- Use focused validation when changing package behavior:
+
+```bash
+yarn jest packages/<package> --runInBand --coverage=false
+```
+
+## Documentation
+
+- Keep `README.md` concise and usage-oriented.
+- Start package READMEs with `# @vyriy/<package>`.
+- Document real public exports, supported options, and examples that actually work.
+- Keep `doc.mdx` as the Storybook/docs wrapper for the README when the package participates in docs.
+- For component packages, include Storybook coverage for supported states and common usage.
+
+## Components
+
+- Prefer lightweight React 19+ components with TypeScript.
+- Keep components SSR-friendly and avoid browser globals during render.
+- Prefer composable props and Bootstrap-compatible ergonomics where practical.
+- Put each public component in its own file with a matching test.
+- Add Storybook stories when a component has visual states, variants, or interaction states.
+
+## Change Discipline
+
+- Keep changes scoped to the requested behavior.
+- Avoid unrelated refactors and metadata churn.
+- Sync implementation, tests, README, `doc.mdx`, and public re-exports together.
+- Prefer the option that is simpler to explain, easier to evolve, and calmer to maintain.

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,12 +1,13 @@
 {
   "name": "@vyriy/router",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Router utility for Vyriy projects",
   "type": "module",
   "main": "./index.js",
   "dependencies": {
     "@types/aws-lambda": "^8.10.161"
   },
+  "agents": "./AGENTS.md",
   "license": "MIT",
   "repository": {
     "type": "git",

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>;
 };