shokupan 0.5.0 → 0.6.1

package/README.md

@@ -7,6 +7,8 @@ Shokupan is designed to make building APIs delightful again. With zero-config de
 
 ### Note: Shokupan is still in alpha and is not guaranteed to be stable. Please use with caution. We will be adding more features and APIs in the future. Please file an issue if you find any bugs or have suggestions for improvement.
 
+📚 **[Full documentation available at https://shokupan.dev](https://shokupan.dev)**
+
 ## ✨ Features
 
 - 🎯 **TypeScript First** - End-to-end type safety with decorators and generics. No manual types needed.
@@ -75,6 +77,7 @@ That's it! Your server is running at `http://localhost:3000` 🎉
   - [Using Express Middleware](#using-express-middleware)
 - [Testing](#testing)
 - [Deployment](#deployment)
+- [Production Best Practices](https://knackstedt.github.io/shokupan/guides/production/) 📚
 - [CLI Tools](#cli-tools)
 - [API Reference](#api-reference)
 - [Roadmap](#-roadmap)
@@ -929,7 +932,7 @@ This works great when combined with the Debug Dashboard.
 A visual dashboard to inspect your application, view metrics, analyze the middleware graph, and replay failed requests.
 
 ```typescript
-import { DebugDashboard } from 'shokupan/plugins/debugview';
+import { DebugDashboard } from 'shokupan';
 
 // Mount the dashboard
 app.mount('/debug', new DebugDashboard({
@@ -1057,8 +1060,8 @@ router.get('/wines/white', async (ctx) => {
 router.get('/wines/all', async (ctx) => {
     // Make parallel sub-requests
     const [redResponse, whiteResponse] = await Promise.all([
-        router.subRequest('/wines/red'),
-        router.subRequest('/wines/white')
+        router.internalRequest('/wines/red'),
+        router.internalRequest('/wines/white')
     ]);
     
     const red = await redResponse.json();
@@ -1559,7 +1562,7 @@ describe('My App', () => {
         app.get('/', () => ({ message: 'Hello' }));
         
         // Process a request without starting the server
-        const res = await app.processRequest({
+        const res = await app.testRequest({
             method: 'GET',
             path: '/'
         });
@@ -1703,8 +1706,8 @@ const app = new Shokupan(config?: ShokupanConfig);
 - `mount(path, controller)` - Mount controller or router
 - `static(path, options)` - Serve static files
 - `listen(port?)` - Start server
-- `processRequest(options)` - Process request (testing)
-- `subRequest(options)` - Make sub-request
+- `testRequest(options)` - Process request (for testing purposes)
+- `internalRequest(options)` - Make sub-request
 - `computeOpenAPISpec(base)` - Generate OpenAPI spec
 
 ### ShokupanRouter Class
@@ -1737,8 +1740,8 @@ const router = new ShokupanRouter(config?: ShokupanRouteConfig);
 - `head(path, spec?, ...handlers)` - Add HEAD route
 - `mount(path, controller)` - Mount controller or router
 - `static(path, options)` - Serve static files
-- `processRequest(options)` - Process request (testing)
-- `subRequest(options)` - Make sub-request
+- `testRequest(options)` - Process request (for testing purposes)
+- `internalRequest(options)` - Make sub-request
 
 
 ### ShokupanContext

package/dist/cli.cjs

@@ -4,7 +4,7 @@ const p = require("@clack/prompts");
 const fs = require("node:fs");
 const path = require("node:path");
 const promises = require("node:timers/promises");
-const openapiAnalyzer = require("./openapi-analyzer-z-7AoFRC.cjs");
+const openapiAnalyzer = require("./openapi-analyzer-Bei1sVWp.cjs");
 function _interopNamespaceDefault(e) {
   const n = Object.create(null, { [Symbol.toStringTag]: { value: "Module" } });
   if (e) {

package/dist/cli.js

@@ -3,7 +3,7 @@ import * as p from "@clack/prompts";
 import fs from "node:fs";
 import path from "node:path";
 import { setTimeout } from "node:timers/promises";
-import { analyzeDirectory } from "./openapi-analyzer-D7y6Qa38.js";
+import { analyzeDirectory } from "./openapi-analyzer-Ce_7JxZh.js";
 const templates = {
   controller: (name) => `import { Controller, Get, Ctx } from 'shokupan';
 import { ShokupanContext } from 'shokupan';

package/dist/context.d.ts

@@ -18,19 +18,89 @@ export interface DebugCollector {
     setNode(id: string): void;
     getCurrentNode(): string | undefined;
 }
-export declare class ShokupanContext<State extends Record<string, any> = Record<string, any>> {
+/**
+ * Shokupan Request Context
+ *
+ * The context object passed to all middleware and route handlers.
+ * Provides access to request data, response helpers, and typed state management.
+ *
+ * @template State - The shape of `ctx.state` for type-safe state access across middleware.
+ * @template Params - The shape of `ctx.params` based on the route path pattern.
+ *
+ * @example Basic Usage
+ * ```typescript
+ * app.get('/hello', (ctx) => {
+ *   return ctx.json({ message: 'Hello' });
+ * });
+ * ```
+ *
+ * @example Typed State
+ * ```typescript
+ * interface AppState {
+ *   userId: string;
+ *   requestId: string;
+ * }
+ *
+ * const app = new Shokupan<AppState>();
+ *
+ * app.use((ctx, next) => {
+ *   ctx.state.requestId = crypto.randomUUID(); // ✓ Type-safe
+ *   return next();
+ * });
+ * ```
+ *
+ * @example Typed Path Parameters
+ * ```typescript
+ * app.get('/users/:userId/posts/:postId', (ctx) => {
+ *   // ctx.params is automatically typed as { userId: string; postId: string }
+ *   const { userId, postId } = ctx.params;
+ *   return ctx.json({ userId, postId });
+ * });
+ * ```
+ *
+ * @example Full Type Safety (State + Params)
+ * ```typescript
+ * interface RequestState {
+ *   userId: string;
+ *   permissions: string[];
+ * }
+ *
+ * const app = new Shokupan<RequestState>();
+ *
+ * app.get('/admin/users/:userId', (ctx) => {
+ *   // Both typed!
+ *   const { userId } = ctx.params;        // ✓ From path
+ *   const { permissions } = ctx.state;     // ✓ From state
+ *
+ *   if (!permissions.includes('admin')) {
+ *     return ctx.json({ error: 'Forbidden' }, 403);
+ *   }
+ *   return ctx.json({ userId });
+ * });
+ * ```
+ */
+export declare class ShokupanContext<State extends Record<string, any> = Record<string, any>, Params extends Record<string, string> = Record<string, string>> {
     readonly request: ShokupanRequest<any>;
     readonly server?: Server;
     readonly app?: Shokupan;
     readonly signal?: AbortSignal;
-    private _url;
-    params: Record<string, string>;
+    params: Params;
     state: State;
     handlerStack: HandlerStackItem[];
     readonly response: ShokupanResponse;
     _debug?: DebugCollector;
     _finalResponse?: Response;
     _rawBody?: string | ArrayBuffer | Uint8Array;
+    private _url?;
+    private _cachedBody?;
+    private _bodyType?;
+    private _bodyParsed;
+    _bodyParseError?: Error;
+    private _cachedHostname?;
+    private _cachedProtocol?;
+    private _cachedHost?;
+    private _cachedOrigin?;
+    private _cachedQuery?;
     constructor(request: ShokupanRequest<any>, server?: Server, state?: State, app?: Shokupan, signal?: AbortSignal, // Optional as it might not be provided in tests or simple creates
     enableMiddlewareTracking?: boolean);
     get url(): URL;
@@ -101,6 +171,23 @@ export declare class ShokupanContext<State extends Record<string, any> = Record<
      */
     setCookie(name: string, value: string, options?: CookieOptions): this;
     private mergeHeaders;
+    /**
+     * Read request body with caching to avoid double parsing.
+     * The body is only parsed once and cached for subsequent reads.
+     */
+    body<T = any>(): Promise<T>;
+    /**
+     * Pre-parse the request body before handler execution.
+     * This improves performance and enables Node.js compatibility for large payloads.
+     * Errors are deferred until the body is actually accessed in the handler.
+     */
+    parseBody(): Promise<void>;
+    /**
+     * Read raw body from ReadableStream efficiently.
+     * This is much faster than request.text() for large payloads.
+     * Also handles the case where body is already a string (e.g., in tests).
+     */
+    private readRawBody;
     /**
      * Send a response
      * @param body Response body
@@ -108,10 +195,6 @@ export declare class ShokupanContext<State extends Record<string, any> = Record<
      * @returns Response
      */
     send(body?: BodyInit, options?: ResponseInit): Response;
-    /**
-     * Read request body
-     */
-    body<T = any>(): Promise<T>;
     /**
      * Respond with a JSON object
      */