@vyriy/server 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

@@ -32,58 +32,54 @@ server(async () => ({
 }));
 ```
 
-Run a Lambda response streaming handler locally:
+Use `api(...)` when you want the handler package wrappers. It keeps the same `(event, context)` Lambda handler shape.
 
 ```ts
-import { api, streamify } from '@vyriy/handler';
+import { api } from '@vyriy/handler';
 import { server } from '@vyriy/server';
 
-server(
-  streamify(
-    api(async (event, responseStream) => {
-      responseStream.setContentType?.('text/plain');
-      responseStream.write(`Path: ${event.path}\n`);
-      responseStream.end('Done');
-    }),
-  ),
-);
-```
+const handler = api(async (event) => ({
+  statusCode: 200,
+  body: JSON.stringify({
+    ok: true,
+    path: event.path,
+  }),
+}));
 
-Keep the AWS-specific `awslambda.streamifyResponse(handler)` wrapper in a separate Lambda entrypoint.
+server(handler);
+```
 
-Serve static files through `@vyriy/router` prefix routes:
+Run a Lambda response streaming handler locally:
 
 ```ts
-import { createRouter } from '@vyriy/router';
-import { staticFiles } from '@vyriy/server/static';
+import { streamServer } from '@vyriy/server';
 
-const router = createRouter().prefix('/static', staticFiles('./public'));
+streamServer(async (event, responseStream) => {
+  responseStream.setContentType?.('text/plain');
+  responseStream.write(`Path: ${event.path}\n`);
+  responseStream.end('Done');
+});
 ```
 
-Serve a static directory directly when the server only needs files:
+The stream handler receives the API Gateway-style event first, the response stream second, and the Lambda context third.
+
+Use `streamApi(...)` when you want the handler package wrappers. It keeps the same `(event, responseStream, context)` stream handler shape.
 
 ```ts
-import { server, staticFiles } from '@vyriy/server';
+import { streamApi } from '@vyriy/handler';
+import { streamServer } from '@vyriy/server';
 
-server(
-  staticFiles('./public', {
-    fallback: 'index.html',
-    fallbackStatusCode: 200,
-  }),
-);
+const handler = streamApi((event, responseStream) => {
+  responseStream.setContentType?.('text/plain');
+  responseStream.write(`Path: ${event.path}\n`);
+  responseStream.end('Done');
+});
+
+streamServer(handler);
 ```
 
-By default, missing static files fall back to `404.html` from the same directory with status `404` when that file exists.
-For static apps that should fall back to `index.html`, configure the fallback explicitly:
+Keep the AWS-specific `awslambda.streamifyResponse(handler)` wrapper in a separate Lambda entrypoint.
 
-```ts
-const router = createRouter().prefix(
-  '/static',
-  staticFiles('./public', {
-    fallback: 'index.html',
-    fallbackStatusCode: 200,
-  }),
-);
-```
+Static files are intentionally left to the Docker/web-server layer, for example Nginx, Caddy, or the platform serving assets in front of this Node process.
 
 The server listens on `PORT` from `@vyriy/env`. The default port is `3000`.

package/index.d.ts

@@ -1,3 +1,2 @@
-export { server } from './server.js';
-export { staticFiles } from './static.js';
+export { server, streamServer } from './server.js';
 export type * from './types.js';

package/index.js

@@ -1,2 +1 @@
-export { server } from './server.js';
-export { staticFiles } from './static.js';
+export { server, streamServer } from './server.js';

package/listener.d.ts

@@ -1,2 +1,3 @@
-import type { NativeRequestListener, ServerHandler } from './types.js';
-export declare const listener: (handler: ServerHandler) => NativeRequestListener;
+import type { LambdaHandler, LambdaStreamHandler, NativeRequestListener } from './types.js';
+export declare const listener: (handler: LambdaHandler) => NativeRequestListener;
+export declare const streamListener: (handler: LambdaStreamHandler) => NativeRequestListener;

package/listener.js

@@ -1,6 +1,5 @@
 import { mapParams } from './params.js';
 import { error, result } from './result.js';
-const isStreamHandler = (handler) => handler.length >= 3;
 const createResponseStream = (response) => {
     response.setContentType = (contentType) => response.setHeader?.('content-type', contentType) ?? response;
     return response;
@@ -8,10 +7,6 @@ const createResponseStream = (response) => {
 export const listener = (handler) => async (request, response) => {
     try {
         const { context, event } = await mapParams(request);
-        if (isStreamHandler(handler)) {
-            await handler(event, createResponseStream(response), context);
-            return;
-        }
         const value = await handler(event, context);
         await result(response, value);
     }
@@ -19,3 +14,12 @@ export const listener = (handler) => async (request, response) => {
         error(response);
     }
 };
+export const streamListener = (handler) => async (request, response) => {
+    try {
+        const { context, event } = await mapParams(request);
+        await handler(event, createResponseStream(response), context);
+    }
+    catch {
+        error(response);
+    }
+};

package/package.json

@@ -1,16 +1,15 @@
 {
   "name": "@vyriy/server",
-  "version": "0.3.0",
+  "version": "0.3.4",
   "description": "Small HTTP server adapter for Lambda-style Vyriy handlers",
   "type": "module",
   "main": "./index.js",
   "dependencies": {
     "@types/aws-lambda": "^8.10.161",
-    "@vyriy/env": "0.3.0",
-    "@vyriy/error": "0.3.0",
-    "@vyriy/handler": "0.3.0",
-    "@vyriy/logger": "0.3.0",
-    "@vyriy/router": "0.3.0"
+    "@vyriy/env": "0.3.4",
+    "@vyriy/error": "0.3.4",
+    "@vyriy/handler": "0.3.4",
+    "@vyriy/logger": "0.3.4"
   },
   "agents": "./AGENTS.md",
   "license": "MIT",
@@ -115,16 +114,6 @@
       "types": "./shutdown.d.ts",
       "import": "./shutdown.js",
       "default": "./shutdown.js"
-    },
-    "./static": {
-      "types": "./static.d.ts",
-      "import": "./static.js",
-      "default": "./static.js"
-    },
-    "./static.js": {
-      "types": "./static.d.ts",
-      "import": "./static.js",
-      "default": "./static.js"
     }
   }
 }

package/server.d.ts

@@ -1,2 +1,3 @@
-import type { CreateServer } from './types.js';
+import type { CreateServer, CreateStreamServer } from './types.js';
 export declare const server: CreateServer;
+export declare const streamServer: CreateStreamServer;

package/server.js

@@ -1,4 +1,5 @@
 import * as http from 'node:http';
-import { listener } from './listener.js';
+import { listener, streamListener } from './listener.js';
 import { listen } from './listen.js';
 export const server = (handler) => listen(http.createServer(listener(handler)));
+export const streamServer = (handler) => listen(http.createServer(streamListener(handler)));

package/types.d.ts

@@ -7,7 +7,6 @@ export type LambdaEvent = APIGatewayProxyEvent;
 export type LambdaResult = APIGatewayProxyResult;
 export type LambdaHandler = (event: LambdaEvent, context: Context) => Promise<LambdaResult>;
 export type LambdaStreamHandler = (event: LambdaEvent, responseStream: ResponseStream, context: Context) => Promise<LambdaResult | void>;
-export type ServerHandler = LambdaHandler | LambdaStreamHandler;
 export type RequestMessage = {
     headers: IncomingHttpHeaders;
     method?: string;
@@ -42,4 +41,5 @@ export type Listen = (server: Server) => Server;
 export type NormalizeHeaders = (headers: IncomingHttpHeaders) => Record<string, string | undefined>;
 export type WriteResult<Response extends ResponseMessage = ResponseMessage> = (response: Response, result: LambdaResult | void) => Promise<void> | void;
 export type WriteError<Response extends ResponseMessage = ResponseMessage> = (response: Response) => void;
-export type CreateServer = (handler: ServerHandler) => Server;
+export type CreateServer = (handler: LambdaHandler) => Server;
+export type CreateStreamServer = (handler: LambdaStreamHandler) => Server;

package/static.d.ts

@@ -1,8 +0,0 @@
-import type { APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda';
-import type { Handler } from '@vyriy/router';
-export type StaticFilesOptions = {
-    fallback?: false | string;
-    fallbackStatusCode?: number;
-};
-export type StaticFilesHandler = Handler & ((event: APIGatewayProxyEvent) => Promise<APIGatewayProxyResult>);
-export declare const staticFiles: (directory: string, options?: StaticFilesOptions) => StaticFilesHandler;

package/static.js

@@ -1,120 +0,0 @@
-import { STATUS_CODES } from 'node:http';
-import { readFile, stat } from 'node:fs/promises';
-import { extname, resolve, sep } from 'node:path';
-const CONTENT_TYPES = {
-    '.css': 'text/css; charset=utf-8',
-    '.gif': 'image/gif',
-    '.html': 'text/html; charset=utf-8',
-    '.ico': 'image/x-icon',
-    '.jpeg': 'image/jpeg',
-    '.jpg': 'image/jpeg',
-    '.js': 'text/javascript; charset=utf-8',
-    '.json': 'application/json; charset=utf-8',
-    '.mjs': 'text/javascript; charset=utf-8',
-    '.png': 'image/png',
-    '.svg': 'image/svg+xml; charset=utf-8',
-    '.txt': 'text/plain; charset=utf-8',
-    '.webp': 'image/webp',
-};
-const getContentType = (filePath) => CONTENT_TYPES[extname(filePath).toLowerCase()] ?? 'application/octet-stream';
-const notFound = () => ({
-    body: JSON.stringify({
-        message: STATUS_CODES[404],
-    }),
-    headers: {
-        'content-type': 'application/json',
-    },
-    statusCode: 404,
-});
-const methodNotAllowed = () => ({
-    body: JSON.stringify({
-        message: STATUS_CODES[405],
-    }),
-    headers: {
-        allow: 'GET, HEAD',
-        'content-type': 'application/json',
-    },
-    statusCode: 405,
-});
-const getFilePath = (directory, relativePath) => {
-    const rootPath = resolve(directory);
-    const filePath = resolve(rootPath, relativePath.replace(/^\/+/, '') || 'index.html');
-    if (filePath !== rootPath && !filePath.startsWith(`${rootPath}${sep}`)) {
-        return undefined;
-    }
-    return filePath;
-};
-const readFileResponse = async (filePath, method, statusCode = 200) => {
-    const file = await stat(filePath);
-    if (!file.isFile()) {
-        return undefined;
-    }
-    const headers = {
-        'content-length': String(file.size),
-        'content-type': getContentType(filePath),
-    };
-    if (method === 'HEAD') {
-        return {
-            body: '',
-            headers,
-            statusCode,
-        };
-    }
-    return {
-        body: (await readFile(filePath)).toString('base64'),
-        headers,
-        isBase64Encoded: true,
-        statusCode,
-    };
-};
-const readFallbackResponse = async (directory, method, options) => {
-    if (options.fallback === false) {
-        return undefined;
-    }
-    const fallbackPath = getFilePath(directory, options.fallback);
-    if (!fallbackPath) {
-        return undefined;
-    }
-    try {
-        return await readFileResponse(fallbackPath, method, options.fallbackStatusCode);
-    }
-    catch {
-        return undefined;
-    }
-};
-const isRouterParams = (value) => 'event' in value;
-const getRequest = (value) => {
-    if (isRouterParams(value)) {
-        return {
-            event: value.event,
-            relativePath: value.pathParameters?.proxy ?? '',
-        };
-    }
-    return {
-        event: value,
-        relativePath: value.path.replace(/^\/+/, ''),
-    };
-};
-export const staticFiles = (directory, options = {}) => async (params) => {
-    const { event, relativePath } = getRequest(params);
-    const normalizedOptions = {
-        fallback: '404.html',
-        fallbackStatusCode: 404,
-        ...options,
-    };
-    if (event.httpMethod !== 'GET' && event.httpMethod !== 'HEAD') {
-        return methodNotAllowed();
-    }
-    const filePath = getFilePath(directory, relativePath);
-    if (!filePath) {
-        return (await readFallbackResponse(directory, event.httpMethod, normalizedOptions)) ?? notFound();
-    }
-    try {
-        return ((await readFileResponse(filePath, event.httpMethod)) ??
-            (await readFallbackResponse(directory, event.httpMethod, normalizedOptions)) ??
-            notFound());
-    }
-    catch {
-        return (await readFallbackResponse(directory, event.httpMethod, normalizedOptions)) ?? notFound();
-    }
-};