shokupan 0.6.0 → 0.6.1

package/dist/plugins/proxy.d.ts

@@ -5,5 +5,7 @@ export interface ProxyOptions {
     changeOrigin?: boolean;
     ws?: boolean;
     headers?: Record<string, string>;
+    allowedHosts?: string[];
+    allowPrivateIPs?: boolean;
 }
 export declare function Proxy(options: ProxyOptions): Middleware;

package/dist/plugins/rate-limit.d.ts

@@ -10,5 +10,6 @@ export interface RateLimitOptions {
     keyGenerator?: (ctx: ShokupanContext) => string;
     skip?: (ctx: ShokupanContext) => boolean;
     mode?: 'user' | 'absolute';
+    trustedProxies?: string[];
 }
 export declare function RateLimitMiddleware(options?: RateLimitOptions): Middleware;

package/dist/router.d.ts

@@ -1,10 +1,69 @@
 import { ShokupanContext } from './context';
 import { Shokupan } from './shokupan';
 import { $appRoot, $childControllers, $childRouters, $isApplication, $isMounted, $isRouter, $mountPath, $parent, $routes } from './symbol';
-import { GuardAPISpec, JSXRenderer, Method, MethodAPISpec, Middleware, OpenAPIOptions, ProcessResult, RequestOptions, RouteMetadata, ShokupanController, ShokupanHandler, ShokupanHooks, ShokupanRoute, ShokupanRouteConfig, StaticServeOptions } from './types';
+import { GuardAPISpec, JSXRenderer, Method, MethodAPISpec, Middleware, OpenAPIOptions, ProcessResult, RequestOptions, RouteMetadata, RouteParams, ShokupanController, ShokupanHandler, ShokupanHooks, ShokupanRoute, ShokupanRouteConfig, StaticServeOptions } from './types';
 type HeadersInit = Headers | Record<string, string> | [string, string][];
 export declare const RouterRegistry: Map<string, ShokupanRouter<any>>;
 export declare const ShokupanApplicationTree: {};
+/**
+ * Shokupan Router
+ *
+ * A router for organizing and grouping routes with shared middleware and configuration.
+ *
+ * @template State - The shape of `ctx.state` for all routes in this router.
+ * Provides type safety for state management within the router's middleware and handlers.
+ *
+ * @example Basic Router
+ * ```typescript
+ * const router = new ShokupanRouter();
+ * router.get('/users', (ctx) => ctx.json({ users: [] }));
+ *
+ * app.mount('/api', router);
+ * // Routes: GET /api/users
+ * ```
+ *
+ * @example Typed State Router
+ * ```typescript
+ * interface AuthState {
+ *   userId: string;
+ *   isAuthenticated: boolean;
+ * }
+ *
+ * class AuthRouter extends ShokupanRouter<AuthState> {
+ *   constructor() {
+ *     super();
+ *
+ *     // Router middleware has typed state
+ *     this.use((ctx, next) => {
+ *       ctx.state.userId = 'user-123';
+ *       ctx.state.isAuthenticated = true;
+ *       return next();
+ *     });
+ *
+ *     this.get('/me', (ctx) => {
+ *       // State is fully typed
+ *       return ctx.json({ userId: ctx.state.userId });
+ *     });
+ *   }
+ * }
+ *
+ * app.mount('/auth', new AuthRouter());
+ * ```
+ *
+ * @example Router with Middleware
+ * ```typescript
+ * const apiRouter = new ShokupanRouter();
+ *
+ * // Router-level middleware
+ * apiRouter.use(async (ctx, next) => {
+ *   console.log(`API request: ${ctx.method} ${ctx.path}`);
+ *   return next();
+ * });
+ *
+ * apiRouter.get('/status', (ctx) => ctx.json({ status: 'ok' }));
+ * app.mount('/api', apiRouter);
+ * ```
+ */
 export declare class ShokupanRouter<T extends Record<string, any> = Record<string, any>> {
     readonly config?: ShokupanRouteConfig;
     private [$isApplication];
@@ -34,7 +93,7 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
         enableMiddlewareTracking?: boolean;
         middlewareTrackingMaxCapacity?: number;
         middlewareTrackingTTL?: number;
-        httpLogger?: (ctx: ShokupanContext<Record<string, any>>) => void;
+        httpLogger?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>) => void;
         logger?: {
             verbose?: boolean;
             info?: (msg: string, props: Record<string, any>) => void;
@@ -49,27 +108,27 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
         renderer?: JSXRenderer;
         serverFactory?: import('./types').ServerFactory;
         hooks?: {
-            onError?: (ctx: ShokupanContext<Record<string, any>>, error: unknown) => void | Promise<void>;
-            onRequestStart?: (ctx: ShokupanContext<Record<string, any>>) => void | Promise<void>;
-            onRequestEnd?: (ctx: ShokupanContext<Record<string, any>>) => void | Promise<void>;
-            onResponseStart?: (ctx: ShokupanContext<Record<string, any>>, response: Response) => void | Promise<void>;
-            onResponseEnd?: (ctx: ShokupanContext<Record<string, any>>, response: Response) => void | Promise<void>;
-            beforeValidate?: (ctx: ShokupanContext<Record<string, any>>, data: any) => void | Promise<void>;
-            afterValidate?: (ctx: ShokupanContext<Record<string, any>>, data: any) => void | Promise<void>;
-            onReadTimeout?: (ctx: ShokupanContext<Record<string, any>>) => void | Promise<void>;
-            onWriteTimeout?: (ctx: ShokupanContext<Record<string, any>>) => void | Promise<void>;
-            onRequestTimeout?: (ctx: ShokupanContext<Record<string, any>>) => void | Promise<void>;
+            onError?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>, error: unknown) => void | Promise<void>;
+            onRequestStart?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>) => void | Promise<void>;
+            onRequestEnd?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>) => void | Promise<void>;
+            onResponseStart?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>, response: Response) => void | Promise<void>;
+            onResponseEnd?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>, response: Response) => void | Promise<void>;
+            beforeValidate?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>, data: any) => void | Promise<void>;
+            afterValidate?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>, data: any) => void | Promise<void>;
+            onReadTimeout?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>) => void | Promise<void>;
+            onWriteTimeout?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>) => void | Promise<void>;
+            onRequestTimeout?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>) => void | Promise<void>;
         } | {
-            onError?: (ctx: ShokupanContext<Record<string, any>>, error: unknown) => void | Promise<void>;
-            onRequestStart?: (ctx: ShokupanContext<Record<string, any>>) => void | Promise<void>;
-            onRequestEnd?: (ctx: ShokupanContext<Record<string, any>>) => void | Promise<void>;
-            onResponseStart?: (ctx: ShokupanContext<Record<string, any>>, response: Response) => void | Promise<void>;
-            onResponseEnd?: (ctx: ShokupanContext<Record<string, any>>, response: Response) => void | Promise<void>;
-            beforeValidate?: (ctx: ShokupanContext<Record<string, any>>, data: any) => void | Promise<void>;
-            afterValidate?: (ctx: ShokupanContext<Record<string, any>>, data: any) => void | Promise<void>;
-            onReadTimeout?: (ctx: ShokupanContext<Record<string, any>>) => void | Promise<void>;
-            onWriteTimeout?: (ctx: ShokupanContext<Record<string, any>>) => void | Promise<void>;
-            onRequestTimeout?: (ctx: ShokupanContext<Record<string, any>>) => void | Promise<void>;
+            onError?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>, error: unknown) => void | Promise<void>;
+            onRequestStart?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>) => void | Promise<void>;
+            onRequestEnd?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>) => void | Promise<void>;
+            onResponseStart?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>, response: Response) => void | Promise<void>;
+            onResponseEnd?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>, response: Response) => void | Promise<void>;
+            beforeValidate?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>, data: any) => void | Promise<void>;
+            afterValidate?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>, data: any) => void | Promise<void>;
+            onReadTimeout?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>) => void | Promise<void>;
+            onWriteTimeout?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>) => void | Promise<void>;
+            onRequestTimeout?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>) => void | Promise<void>;
         }[];
         validateStatusCodes?: boolean;
     };
@@ -196,7 +255,7 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
      * @param path - URL path
      * @param handlers - Route handler functions
      */
-    get(path: string, ...handlers: ShokupanHandler<T>[]): any;
+    get<Path extends string>(path: Path, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
     /**
      * Adds a GET route to the router.
      *
@@ -204,14 +263,14 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
      * @param spec - OpenAPI specification for the route
      * @param handlers - Route handler functions
      */
-    get(path: string, spec: MethodAPISpec, ...handlers: ShokupanHandler<T>[]): any;
+    get<Path extends string>(path: Path, spec: MethodAPISpec, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
     /**
      * Adds a POST route to the router.
      *
      * @param path - URL path
      * @param handlers - Route handler functions
      */
-    post(path: string, ...handlers: ShokupanHandler<T>[]): any;
+    post<Path extends string>(path: Path, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
     /**
      * Adds a POST route to the router.
      *
@@ -219,14 +278,14 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
      * @param spec - OpenAPI specification for the route
      * @param handlers - Route handler functions
      */
-    post(path: string, spec: MethodAPISpec, ...handlers: ShokupanHandler<T>[]): any;
+    post<Path extends string>(path: Path, spec: MethodAPISpec, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
     /**
      * Adds a PUT route to the router.
      *
      * @param path - URL path
      * @param handlers - Route handler functions
      */
-    put(path: string, ...handlers: ShokupanHandler<T>[]): any;
+    put<Path extends string>(path: Path, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
     /**
      * Adds a PUT route to the router.
      *
@@ -234,14 +293,14 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
      * @param spec - OpenAPI specification for the route
      * @param handlers - Route handler functions
      */
-    put(path: string, spec: MethodAPISpec, ...handlers: ShokupanHandler<T>[]): any;
+    put<Path extends string>(path: Path, spec: MethodAPISpec, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
     /**
      * Adds a DELETE route to the router.
      *
      * @param path - URL path
      * @param handlers - Route handler functions
      */
-    delete(path: string, ...handlers: ShokupanHandler<T>[]): any;
+    delete<Path extends string>(path: Path, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
     /**
      * Adds a DELETE route to the router.
      *
@@ -249,14 +308,14 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
      * @param spec - OpenAPI specification for the route
      * @param handlers - Route handler functions
      */
-    delete(path: string, spec: MethodAPISpec, ...handlers: ShokupanHandler<T>[]): any;
+    delete<Path extends string>(path: Path, spec: MethodAPISpec, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
     /**
      * Adds a PATCH route to the router.
      *
      * @param path - URL path
      * @param handlers - Route handler functions
      */
-    patch(path: string, ...handlers: ShokupanHandler<T>[]): any;
+    patch<Path extends string>(path: Path, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
     /**
      * Adds a PATCH route to the router.
      *
@@ -264,14 +323,14 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
      * @param spec - OpenAPI specification for the route
      * @param handlers - Route handler functions
      */
-    patch(path: string, spec: MethodAPISpec, ...handlers: ShokupanHandler<T>[]): any;
+    patch<Path extends string>(path: Path, spec: MethodAPISpec, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
     /**
      * Adds a OPTIONS route to the router.
      *
      * @param path - URL path
      * @param handlers - Route handler functions
      */
-    options(path: string, ...handlers: ShokupanHandler<T>[]): any;
+    options<Path extends string>(path: Path, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
     /**
      * Adds a OPTIONS route to the router.
      *
@@ -279,14 +338,14 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
      * @param spec - OpenAPI specification for the route
      * @param handlers - Route handler functions
      */
-    options(path: string, spec: MethodAPISpec, ...handlers: ShokupanHandler<T>[]): any;
+    options<Path extends string>(path: Path, spec: MethodAPISpec, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
     /**
      * Adds a HEAD route to the router.
      *
      * @param path - URL path
      * @param handlers - Route handler functions
      */
-    head(path: string, ...handlers: ShokupanHandler<T>[]): any;
+    head<Path extends string>(path: Path, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
     /**
      * Adds a HEAD route to the router.
      *
@@ -294,7 +353,7 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
      * @param spec - OpenAPI specification for the route
      * @param handlers - Route handler functions
      */
-    head(path: string, spec: MethodAPISpec, ...handlers: ShokupanHandler<T>[]): any;
+    head<Path extends string>(path: Path, spec: MethodAPISpec, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
     /**
      * Adds a guard to the router that applies to all routes added **after** this point.
      * Guards must return true or call `ctx.next()` to allow the request to continue.

package/dist/shokupan.d.ts

@@ -3,6 +3,70 @@ import { ShokupanRouter } from './router';
 import { $dispatch } from './symbol';
 import { Middleware, ProcessResult, RequestOptions, ShokupanConfig } from './types';
 import { Server } from 'bun';
+/**
+ * Shokupan Application
+ *
+ * The main application class for creating a Shokupan web server.
+ *
+ * @template State - The shape of `ctx.state` for all routes in the application.
+ * Use this to provide type safety for state management across middleware and handlers.
+ *
+ * @example Basic Usage
+ * ```typescript
+ * const app = new Shokupan();
+ * app.get('/hello', (ctx) => ctx.json({ message: 'Hello' }));
+ * await app.listen(3000);
+ * ```
+ *
+ * @example Typed State
+ * ```typescript
+ * interface AppState {
+ *   userId: string;
+ *   tenant: string;
+ *   requestId: string;
+ * }
+ *
+ * const app = new Shokupan<AppState>();
+ *
+ * // Middleware has typed state access
+ * app.use((ctx, next) => {
+ *   ctx.state.userId = 'user-123';    // ✓ Type-safe
+ *   ctx.state.requestId = crypto.randomUUID();
+ *   return next();
+ * });
+ *
+ * // Handlers have typed state access
+ * app.get('/profile', (ctx) => {
+ *   const { userId, tenant } = ctx.state; // ✓ TypeScript knows these exist
+ *   return ctx.json({ userId, tenant });
+ * });
+ * ```
+ *
+ * @example Empty State (No State Management)
+ * ```typescript
+ * import { EmptyState } from 'shokupan';
+ *
+ * const app = new Shokupan<EmptyState>();
+ * // ctx.state will be an empty object with no properties
+ * ```
+ *
+ * @example Combining Path Params and State
+ * ```typescript
+ * interface RequestState {
+ *   userId: string;
+ *   permissions: string[];
+ * }
+ *
+ * const app = new Shokupan<RequestState>();
+ *
+ * app.get('/users/:userId/posts/:postId', (ctx) => {
+ *   // Both params and state are fully typed!
+ *   const { userId, postId } = ctx.params;  // ✓ Path params typed
+ *   const { permissions } = ctx.state;       // ✓ State typed
+ *   return ctx.json({ userId, postId, permissions });
+ * });
+ * ```
+ */
 export declare class Shokupan<T = any> extends ShokupanRouter<T> {
     readonly applicationConfig: ShokupanConfig;
     openApiSpec?: any;

package/dist/types.d.ts

@@ -6,6 +6,33 @@ import { $isRouter } from './symbol';
 export type DeepPartial<T> = T extends Function ? T : T extends object ? {
     [P in keyof T]?: DeepPartial<T[P]>;
 } : T;
+/**
+ * Helper type for applications that don't use ctx.state.
+ * Prevents accidental property access on state.
+ *
+ * @example
+ * ```typescript
+ * const app = new Shokupan<EmptyState>();
+ * ```
+ */
+export type EmptyState = Record<string, never>;
+/**
+ * Default state type that allows any properties.
+ * This is the default if no state type is specified.
+ *
+ * @example
+ * ```typescript
+ * const app = new Shokupan<DefaultState>();
+ * // Equivalent to: new Shokupan();
+ * ```
+ */
+export type DefaultState = Record<string, any>;
+type ParsePathParams<Path extends string> = Path extends `${infer _Start}:${infer Param}/${infer Rest}` ? {
+    [K in Param | keyof ParsePathParams<`/${Rest}`>]: string;
+} : Path extends `${infer _Start}:${infer Param}` ? {
+    [K in Param]: string;
+} : {};
+export type RouteParams<Path extends string> = string extends Path ? Record<string, string> : ParsePathParams<Path> extends Record<string, never> ? Record<string, string> : ParsePathParams<Path>;
 export interface RouteMetadata {
     file: string;
     line: number;
@@ -49,7 +76,7 @@ export interface CookieOptions {
     sameSite?: boolean | 'lax' | 'strict' | 'none' | 'Lax' | 'Strict' | 'None';
     priority?: 'low' | 'medium' | 'high' | 'Low' | 'Medium' | 'High';
 }
-export type ShokupanHandler<T extends Record<string, any> = Record<string, any>> = (ctx: ShokupanContext<T>, next?: NextFn) => Promise<any> | any;
+export type ShokupanHandler<State extends Record<string, any> = Record<string, any>, Params extends Record<string, string> = Record<string, string>> = (ctx: ShokupanContext<State, Params>, next?: NextFn) => Promise<any> | any;
 export declare const HTTPMethods: string[];
 export type Method = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "OPTIONS" | "HEAD" | "ALL";
 export declare enum RouteParamType {
@@ -350,6 +377,10 @@ export interface StaticServeOptions<T extends Record<string, any>> {
     root?: string;
     /**
      * Whether to list directory contents if no index file is found.
+     *
+     * Security Note: Directory listing is disabled by default to prevent information disclosure.
+     * Enable this only if you specifically need it and understand the security implications.
+     *
      * @default false
      */
     listDirectory?: boolean;
@@ -384,3 +415,4 @@ export interface StaticServeOptions<T extends Record<string, any>> {
      */
     openapi?: MethodAPISpec;
 }
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "shokupan",
-    "version": "0.6.0",
+    "version": "0.6.1",
     "description": "Shokupan is a low-lift modern web framework for Bun.",
     "author": "Andrew G. Knackstedt",
     "publishConfig": {
@@ -152,4 +152,4 @@
         "vite-plugin-dts": "^4.5.4",
         "zod": "^4.2.1"
     }
-}
+}