@vyriy/router 0.3.0 → 0.3.4

package/AGENTS.md

@@ -1,41 +1,62 @@
-# Vyriy Package Agent Guide
+# Project Agent Guide
 
-This package belongs to the Vyriy toolkit. Keep changes calm, explicit, reusable, and easy to reason about.
+This repository follows a calm engineering style: changes should be explicit, reusable, typed, documented, tested, and easy to reason about.
 
-## Architecture
+Use this guide as the default behavior for AI agents and contributors working in this repository. Prefer local package conventions when they are more specific than this document.
+
+## Core Principles
 
 - Prefer simple modules over clever frameworks or hidden conventions.
-- Keep package boundaries explicit and avoid project-specific coupling.
+- Keep package and project boundaries explicit.
+- Avoid project-specific coupling in reusable code.
 - 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.
+- Prefer SSR-friendly and SSG-friendly code paths when working with frontend or shared code.
+- Keep integrations replaceable and avoid hard coupling to a CMS, framework, vendor, or runtime host.
+- Prefer infrastructure assumptions that are easy to deploy, observe, and replace.
+- Prefer the option that is simpler to explain, easier to evolve, and calmer to maintain.
 
 ## File Shape
 
-- Prefer one exported runtime method, component, or helper per production file when it stays readable.
+- Prefer one exported runtime method, component, helper, or class 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.
+- Use relative import and export specifiers that match the package module style.
+- Use `.js` relative specifiers in TypeScript source for ESM/NodeNext packages.
 - 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.
+- Every new public export must be re-exported from the package or module public entry point.
+- Add or update public-surface tests when exports change.
 - 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.
+- Avoid exporting internal helpers only to make tests easier.
+- Do not hand-maintain package `exports` maps unless the project 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.
+- Keep tests deterministic.
+- Avoid real network, filesystem, timers, browser, or cloud dependencies unless the behavior specifically requires them.
 - When mocking modules, install mocks before loading the module under test.
-- Use focused validation when changing package behavior:
+- Use focused validation when changing behavior.
+
+Example validation commands:
+
+```bash
+yarn test
+```
+
+For workspaces, prefer the project convention, for example:
+
+```bash
+yarn workspace <package-name> test
+```
+
+For Jest-based packages, focused validation may look like:
 
 ```bash
 yarn jest packages/<package> --runInBand --coverage=false
@@ -44,22 +65,38 @@ yarn jest packages/<package> --runInBand --coverage=false
 ## Documentation
 
 - Keep `README.md` concise and usage-oriented.
-- Start package READMEs with `# @vyriy/<package>`.
+- Start package READMEs with `# <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.
+- Update docs when public behavior changes.
+- Keep generated docs wrappers, such as `doc.mdx`, aligned with the README when the project uses them.
+- For component packages, include visual documentation or stories for supported states and common usage.
 
 ## Components
 
-- Prefer lightweight React 19+ components with TypeScript.
+- Prefer lightweight React components with TypeScript when working in React packages.
 - Keep components SSR-friendly and avoid browser globals during render.
-- Prefer composable props and Bootstrap-compatible ergonomics where practical.
+- Prefer composable props and predictable ergonomics.
 - 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.
+- Add stories or examples when a component has visual states, variants, or interaction states.
+- Keep styling explicit and reusable. Avoid hidden theme assumptions unless they are part of the package contract.
 
 ## 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.
+- Sync implementation, tests, docs, examples, and public re-exports together.
+- Do not introduce new dependencies unless they clearly reduce complexity or are already part of the project direction.
+- Prefer small, reviewable changes over broad rewrites.
+- Preserve existing conventions unless there is a clear reason to change them.
+
+## Before Finishing
+
+Check that the change is complete:
+
+- Public exports are updated.
+- Public-surface tests are updated when exports change.
+- Matching unit tests exist for new behavior.
+- README examples still match the real API.
+- Visual docs, stories, or examples are updated for visible component behavior.
+- TypeScript imports follow the package module style.
+- No unrelated files, formatting churn, or generated artifacts were changed.

package/README.md

@@ -9,7 +9,6 @@ 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
 
@@ -29,16 +28,14 @@ With Yarn:
 yarn add @vyriy/router
 ```
 
-## Usage
+## Basic Router
 
 ```ts
 import { createRouter } from '@vyriy/router';
-import { staticFiles } from '@vyriy/server/static';
 
 const router = createRouter();
 
 router.get('/health', async ({ event, query, headers, pathParameters, body }) => ({
-  statusCode: 200,
   body: JSON.stringify({
     ok: true,
     method: event.httpMethod,
@@ -49,8 +46,6 @@ router.get('/health', async ({ event, query, headers, pathParameters, body }) =>
   }),
 }));
 
-router.prefix('/static', staticFiles('./public'));
-
 router.fallback(async ({ event }) => ({
   statusCode: 404,
   body: JSON.stringify({
@@ -58,16 +53,98 @@ router.fallback(async ({ event }) => ({
     path: event.path,
   }),
 }));
+
+export const handler = (event: Parameters<typeof router.route>[0]) => router.route(event);
 ```
 
-Prefix handlers receive the relative matched path in `pathParameters.proxy`, so they can behave like normal handlers:
+## 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
-router.prefix('/events', async ({ pathParameters, responseStream }) => {
-  responseStream?.setContentType?.('text/plain');
-  responseStream?.write(`Path: ${pathParameters?.proxy}`);
-  responseStream?.end();
+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
@@ -75,28 +152,33 @@ router.prefix('/events', async ({ pathParameters, responseStream }) => {
 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.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.
+- `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.prefix(pathPrefix, handler)`
 - `router.fallback(handler)`
 - `router.route(event)`
+- `streamRouter.on(method, path, handler)`
+- `streamRouter.fallback(handler)`
+- `streamRouter.route(event, responseStream)`
 
 Route handlers receive:
 
@@ -106,7 +188,12 @@ type HandlerParams = {
   body?: string;
   headers?: APIGatewayProxyEvent['headers'];
   pathParameters?: APIGatewayProxyEvent['pathParameters'];
-  responseStream?: ResponseStream;
   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 = {
@@ -26,13 +26,42 @@ export const createRouter = () => {
             router.on('PATCH', path, handler);
             return api;
         },
-        prefix(pathPrefix, handler) {
-            router.prefix(pathPrefix, handler);
-            return api;
-        },
         route(event) {
             return router.route(event);
         },
     };
     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.3.0",
+  "version": "0.3.4",
   "description": "Router utility for Vyriy projects",
   "type": "module",
   "main": "./index.js",

package/router.d.ts

@@ -1,10 +1,14 @@
-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;
-    fallback(handler: Handler): this;
-    prefix(pathPrefix: string, handler: Handler): this;
-    route(event: APIGatewayProxyEvent, responseStream?: ResponseStream): Promise<RouteResult | void>;
+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,25 +1,5 @@
 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,
@@ -27,34 +7,31 @@ const normalizeResult = (result) => ({
     isBase64Encoded: result.isBase64Encoded,
     multiValueHeaders: result.multiValueHeaders,
 });
-export class Router {
+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 = {};
-    staticRoutes = [];
     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;
     }
-    prefix(pathPrefix, handler) {
-        this.staticRoutes.push({
-            handler,
-            pathPrefix: removeTrailingSlashes(pathPrefix) || '/',
-        });
-        return this;
-    }
-    async route(event, responseStream) {
+}
+export class Router extends BaseRouter {
+    async route(event) {
         const { httpMethod, path, queryStringParameters, body, headers, pathParameters } = event;
         const exactHandler = this.routes[httpMethod]?.[path];
         if (exactHandler) {
@@ -63,30 +40,9 @@ export class Router {
                 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;
-            }
+            return normalizeResult(result);
         }
         if (this.fallbackHandler) {
             const fallbackResult = await this.fallbackHandler({
@@ -94,10 +50,9 @@ export class Router {
                 body: body ?? undefined,
                 headers,
                 pathParameters: pathParameters ?? undefined,
-                responseStream,
                 event,
             });
-            return fallbackResult ? normalizeResult(fallbackResult) : undefined;
+            return normalizeResult(fallbackResult);
         }
         return {
             statusCode: 404,
@@ -107,3 +62,33 @@ export class Router {
         };
     }
 }
+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,6 +1,8 @@
 import type { APIGatewayProxyEvent, APIGatewayProxyEventQueryStringParameters, APIGatewayProxyResult } from 'aws-lambda';
 export type { APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda';
-export type RouteResult = {
+type MaybePromise<Result> = Result | Promise<Result>;
+export type RouteResult = APIGatewayProxyResult;
+export type RouteHandlerResult = {
     body: APIGatewayProxyResult['body'];
     headers?: APIGatewayProxyResult['headers'];
     isBase64Encoded?: APIGatewayProxyResult['isBase64Encoded'];
@@ -21,10 +23,10 @@ export type HandlerParams = {
     body?: string;
     headers?: APIGatewayProxyEvent['headers'];
     pathParameters?: APIGatewayProxyEvent['pathParameters'];
-    responseStream?: ResponseStream;
     event: APIGatewayProxyEvent;
 };
-export type Handler = (params: HandlerParams) => Promise<RouteResult | void>;
+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;
@@ -32,6 +34,14 @@ export type RouterApi = {
     delete(path: string, handler: Handler): RouterApi;
     fallback(handler: Handler): RouterApi;
     patch(path: string, handler: Handler): RouterApi;
-    prefix(pathPrefix: string, handler: Handler): RouterApi;
-    route(event: APIGatewayProxyEvent, responseStream?: ResponseStream): Promise<RouteResult | void>;
+    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>;
 };