shokupan 0.11.0 → 0.12.0

package/dist/plugins/application/dashboard/static/tabulator.css

@@ -16,6 +16,21 @@
     font-weight: bold;
 }
 
+.tabulator-menu .tabulator-menu-separator {
+    border-color: var(--card-border);
+}
+
+.tabulator-popup-container {
+    background-color: var(--bg-card);
+    border: 1px solid var(--card-border);
+    border-radius: 4px;
+    color: var(--text-primary);
+}
+
+.tabulator-menu .tabulator-menu-item:not(.tabulator-menu-item-disabled):hover {
+    background-color: var(--bg-primary);
+}
+
 .tabulator .tabulator-header .tabulator-col {
     background-color: var(--bg-card);
     border-right: 1px solid var(--card-border);
@@ -58,6 +73,7 @@
     border-bottom: 1px solid var(--card-border);
     color: var(--text-primary);
     transition: background-color 100ms ease;
+    min-height: unset !important;
 }
 
 /* Higher specificity to override Tabulator default themes */
@@ -72,12 +88,12 @@
 }
 
 .tabulator .tabulator-row.tabulator-selected {
-    background-color: var(--bg-primary) !important;
+    background-color: var(--table-row-selected-color) !important;
     color: var(--text-primary);
 }
 
 .tabulator .tabulator-row:hover {
-    background-color: var(--bg-primary) !important;
+    background-color: var(--table-row-hover-color) !important;
     color: var(--text-primary);
     cursor: pointer;
 }
@@ -85,7 +101,7 @@
 /* Cells */
 .tabulator .tabulator-row .tabulator-cell {
     border-right: 1px solid var(--card-border);
-    padding: 10px;
+    padding: 6px;
     align-content: center;
 }
 
@@ -115,4 +131,8 @@
 /* Sorting Icons */
 .tabulator .tabulator-header .tabulator-col .tabulator-col-content .tabulator-arrow {
     border-bottom-color: var(--text-secondary);
+}
+
+.tabulator [tabulator-field="timestamp"] {
+    padding: 0 4px !important;
 }

package/dist/plugins/application/dashboard/static/theme.css

@@ -24,6 +24,7 @@
 
     --text-primary: #F0F0F0;
     --text-secondary: var(--palette-dark-accent);
+    --text-flavor: #ffcc80;
     --text-muted: rgba(214, 211, 209, 0.5);
 
     --primary: var(--palette-dark-primary);
@@ -34,12 +35,15 @@
     --card-border: rgba(214, 211, 209, 0.2);
 
     --table-header-border-color: rgba(214, 211, 209, 0.2);
+    --table-row-hover-color: #382818;
+    --table-row-selected-color: #48331e;
 
     --link-color: var(--palette-dark-primary);
     --link-hover: #FFCBA0;
 
     --button-bg: var(--palette-dark-primary);
     --button-text: #1A1614;
+
 }
 
 * {

package/dist/plugins/application/mcp-server/plugin.d.ts

@@ -0,0 +1,39 @@
+import { Shokupan } from '../../../shokupan';
+import { ShokupanPlugin } from '../../../util/types';
+export interface MCPServerPluginOptions {
+    /**
+     * The path to mount the MCP server to.
+     */
+    path?: string;
+    /**
+     * The root directory to scan for OpenAPI documents.
+     */
+    rootDir?: string;
+    /**
+     * Whether to allow the introspection tool.
+     */
+    allowIntrospection?: boolean;
+    /**
+     * Whether to allow tool execution.
+     */
+    allowToolExecution?: boolean;
+}
+/**
+ * Attaches an MCP server to the application.
+ * This MCP server is focus-designed to provide introspection and tool execution capabilities.
+ *
+ * If your application design requires anything custom, implement your own MCP server.
+ */
+export declare class MCPServerPlugin implements ShokupanPlugin {
+    private options;
+    private router;
+    private mcpServer;
+    private transport;
+    private analyzer;
+    constructor(options?: MCPServerPluginOptions);
+    onInit(app: Shokupan): void;
+    private setupRoutes;
+    private registerTools;
+    private registerResources;
+    private registerPrompts;
+}

package/dist/plugins/application/openapi/analyzer.impl.d.ts

@@ -109,6 +109,10 @@ export declare class OpenAPIAnalyzer {
     /**
      * Main analysis entry point
      */
+    /**
+     * Main analysis entry point
+     */
+    private cachedResult?;
     /**
      * Main analysis entry point
      */

package/dist/plugins/middleware/compression.d.ts

@@ -1,13 +1,23 @@
 import { Middleware } from '../../util/types';
 export interface CompressionOptions {
     /**
-     * Minimum byte size to compress
+     * Minimum byte size to compress responses
      */
     threshold?: number;
     /**
-     * Allowed algorithms
+     * Allowed algorithms for response compression
      */
     allowedAlgorithms?: string[];
+    /**
+     * Enable request decompression
+     * @default true
+     */
+    decompress?: boolean;
+    /**
+     * Maximum size of decompressed request body in bytes to prevent zipbomb style attacks
+     * @default 10485760 (10MB)
+     */
+    maxDecompressedSize?: number;
 }
 /**
  * Compression middleware.

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

@@ -49,6 +49,11 @@ export interface RateLimitOptions {
      * List of trusted proxy IPs
      */
     trustedProxies?: string[];
+    /**
+     * Interval in milliseconds to clean up expired entries.
+     * Defaults to windowMs.
+     */
+    cleanupInterval?: number;
 }
 /**
  * Rate limit middleware.

package/dist/router.d.ts

@@ -1,6 +1,5 @@
 import { ShokupanContext } from './context';
 import { Shokupan } from './shokupan';
-import { SurrealDatastore } from './util/datastore';
 import { $appRoot, $childControllers, $childRouters, $isApplication, $isMounted, $isRouter, $mountPath, $parent, $routes } from './util/symbol';
 import { GuardAPISpec, HeadersInit, JSXRenderer, Method, MethodAPISpec, Middleware, OpenAPIOptions, ProcessResult, RequestOptions, RouteMetadata, RouteParams, ShokupanController, ShokupanHandler, ShokupanHooks, ShokupanRoute, ShokupanRouteConfig, StaticServeOptions } from './util/types';
 export declare const RouterRegistry: Map<string, ShokupanRouter<any>>;
@@ -95,7 +94,6 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
     get hasBeforeValidateHook(): boolean;
     get hasAfterValidateHook(): boolean;
     requestTimeout?: number;
-    get db(): SurrealDatastore | undefined;
     private hookCache;
     private hooksInitialized;
     middleware: Middleware[];
@@ -112,6 +110,7 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
         reusePort: boolean;
         controllersOnly: boolean;
         enableTracing?: boolean;
+        queryParserMode?: "extended" | "simple" | "strict";
         jsonParser?: "native" | "parse-json" | "secure-json-parse";
         autoBackpressureFeedback?: boolean;
         autoBackpressureLevel?: number;
@@ -131,11 +130,12 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
             fatal: (msg: string, props: Record<string, any>) => void;
         };
         readTimeout: number;
+        maxBodySize?: number;
         requestTimeout: number;
         writeTimeout: number;
         renderer: JSXRenderer;
         serverFactory: import('.').ServerFactory;
-        adapter?: "bun" | "node" | "wintercg" | import('./util/adapter/adapters').ServerAdapter;
+        adapter?: "bun" | "node" | "wintercg" | import('./util/adapter').ServerAdapter;
         fileSystem?: import('./util/adapter/filesystem').FileSystemAdapter;
         hooks: ShokupanHooks<Record<string, any>> | ShokupanHooks<Record<string, any>>[];
         validateStatusCodes: boolean;
@@ -173,6 +173,7 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
                 spec_url: string;
             }>;
         };
+        securityHeaders?: boolean | any;
     }>;
     get root(): Shokupan<any>;
     [$routes]: ShokupanRoute[];
@@ -185,7 +186,7 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
      * Middleware will run for all routes matched by this router.
      */
     use(middleware: Middleware): this;
-    getComponentRegistry(): {
+    get registry(): {
         metadata: RouteMetadata;
         middleware: {
             name: string;
@@ -245,7 +246,7 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
     /**
      * Registers a controller instance to the router.
      */
-    registerControllerInstance(controller: any): void;
+    bindController(controller: any): void;
     /**
      * Returns all registered event handlers.
      */

package/dist/server.d.ts

@@ -0,0 +1,22 @@
+import { Shokupan } from './shokupan';
+/**
+ * Shokupan Server
+ *
+ * Responsible for the lifecycle of the HTTP server (listen, stop)
+ * and managing the underlying adapter (Bun, Node, etc).
+ */
+export declare class ShokupanServer {
+    private app;
+    private server?;
+    private adapter?;
+    constructor(app: Shokupan);
+    /**
+     * Starts the application server.
+     * @param port The port to listen on.
+     */
+    listen(port?: number): Promise<any>;
+    /**
+     * Stops the server.
+     */
+    stop(closeActiveConnections?: boolean): Promise<void>;
+}

package/dist/shokupan.d.ts

@@ -76,9 +76,11 @@ export declare class Shokupan<T = any> extends ShokupanRouter<T> {
     private asyncApiSpecPromise?;
     private composedMiddleware?;
     private cpuMonitor?;
-    private server?;
+    server?: Server<any>;
+    private httpServer?;
     private datastore?;
     dbPromise?: Promise<any>;
+    private rootTrie?;
     get db(): SurrealDatastore | undefined;
     get logger(): {
         verbose: boolean;
@@ -114,6 +116,17 @@ export declare class Shokupan<T = any> extends ShokupanRouter<T> {
      * This happens after generateOpenApi() but before the server starts listening (or at least before it finishes startup if async).
      */
     onSpecAvailable(callback: (spec: any) => void | Promise<void>): this;
+    /**
+     * Starts the application server.
+     *
+     * @param port - The port to listen on. If not specified, the port from the configuration is used. If that is not specified, port 3000 is used.
+     * @returns The server instance.
+     */
+    /**
+     * Prepare the application for listening.
+     * Use this if you want to initialize the app without starting the server immediately.
+     */
+    start(): Promise<void>;
     /**
      * Starts the application server.
      *
@@ -155,4 +168,14 @@ export declare class Shokupan<T = any> extends ShokupanRouter<T> {
      */
     fetch(req: Request, server?: Server<any>): Promise<Response>;
     private handleRequest;
+    /**
+     * Compiles all routes into a master Trie for O(1) router lookup.
+     * Use this if adding routes dynamically after start (not recommended but possible).
+     */
+    compile(): void;
+    private flattenRoutes;
+    find(method: string, path: string): {
+        handler: import('.').ShokupanHandler<T>;
+        params: Record<string, string>;
+    };
 }

package/dist/util/adapter/bun.d.ts

@@ -0,0 +1,8 @@
+import { Server } from 'bun';
+import { Shokupan } from '../../shokupan';
+import { ServerAdapter } from './interface';
+export declare class BunAdapter implements ServerAdapter {
+    private server?;
+    listen(port: number, app: Shokupan): Promise<Server<any>>;
+    stop(): Promise<void>;
+}

package/dist/util/adapter/index.d.ts

@@ -0,0 +1,4 @@
+export * from './bun';
+export * from './interface';
+export * from './node';
+export * from './wintercg';

package/dist/util/adapter/interface.d.ts

@@ -0,0 +1,12 @@
+import { Server } from 'bun';
+import { Shokupan } from '../../shokupan';
+export interface ServerAdapter {
+    /**
+     * Start listening on the specified port.
+     */
+    listen(port: number, app: Shokupan): Promise<Server<any>>;
+    /**
+     * Stop the server.
+     */
+    stop?(): Promise<void>;
+}

package/dist/util/adapter/node.d.ts

@@ -0,0 +1,8 @@
+import { Server } from 'bun';
+import { Shokupan } from '../../shokupan';
+import { ServerAdapter } from './interface';
+export declare class NodeAdapter implements ServerAdapter {
+    private server?;
+    listen(port: number, app: Shokupan): Promise<Server<any>>;
+    stop(): Promise<void>;
+}

package/dist/util/adapter/wintercg.d.ts

@@ -0,0 +1,5 @@
+import { Shokupan } from '../../shokupan';
+import { ServerAdapter } from './interface';
+export declare class WinterCGAdapter implements ServerAdapter {
+    listen(port: number, app: Shokupan): Promise<any>;
+}

package/dist/util/body-parser.d.ts

@@ -0,0 +1,30 @@
+import { ShokupanRequest } from './request';
+import { ShokupanConfig } from './types';
+/**
+ * Utility class for parsing request bodies.
+ * Handles size limits, parsing, and caching logic detached from the Context.
+ */
+export declare class BodyParser {
+    /**
+     * Parses the body of a request based on Content-Type header.
+     * @param req The ShokupanRequest object
+     * @param config Application configuration for limits and parser options
+     * @returns The parsed body or throws an error
+     */
+    static parse(req: ShokupanRequest<any>, config?: ShokupanConfig): Promise<{
+        type: string;
+        body: any;
+    }>;
+    /**
+     * Parsing helper for JSON
+     */
+    static parseJson(req: ShokupanRequest<any>, parserType: 'native' | 'parse-json' | 'secure-json-parse', maxBodySize: number): Promise<any>;
+    /**
+     * Parsing helper for FormData
+     */
+    static parseFormData(req: ShokupanRequest<any>, maxBodySize: number): Promise<FormData>;
+    /**
+     * Reads raw body as string with size enforcement
+     */
+    static readRawBody(req: ShokupanRequest<any>, maxBodySize: number): Promise<string>;
+}

package/dist/util/decorators.d.ts

@@ -5,9 +5,26 @@ import { AsyncAPISpec, GuardAPISpec, MethodAPISpec, Middleware } from './types';
  */
 export declare function Controller(path?: string): (target: any) => void;
 /**
- * Decorator: Applies middleware to a class or method.
+ * Registers this class as a **Singleton** service.
+ * A single instance will be created and shared across the process.
  */
-export declare function Use(...middleware: Middleware[]): (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => void;
+export declare function Injectable(scope: 'singleton'): ClassDecorator;
+/**
+ * Registers this class as an **Instanced** (Transient) service.
+ * A new instance will be created every time dependency is resolved.
+ */
+export declare function Injectable(scope: 'instanced'): ClassDecorator;
+/**
+ * Property/Parameter Decorator: Injects a service.
+ * Used on class properties or constructor parameters.
+ */
+export declare function Inject(token: any): PropertyDecorator & ParameterDecorator;
+/**
+ * Decorator: Applies middleware OR injects dependencies.
+ * - Class/Method: Middleware
+ * - Property/Parameter: Dependency Injection
+ */
+export declare function Use(tokenOrMiddleware?: any | Middleware, ...moreMiddleware: Middleware[]): (target: any, propertyKey?: string, indexOrDescriptor?: PropertyDescriptor | number) => void;
 /**
  * Decorator: Binds a parameter to the request body.
  */
@@ -76,4 +93,4 @@ export declare function Event(eventName: string): (target: any, propertyKey: str
 /**
  * Decorator: Applies a rate limit to a class or method.
  */
-export declare function RateLimit(options: RateLimitOptions): (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => void;
+export declare function RateLimit(options: RateLimitOptions): (target: any, propertyKey?: string, indexOrDescriptor?: PropertyDescriptor | number) => void;

package/dist/util/di.d.ts

@@ -6,13 +6,8 @@ export declare class Container {
     static register<T>(target: new (...args: any[]) => T, instance: T): void;
     static get<T>(target: new (...args: any[]) => T): T | undefined;
     static has(target: any): boolean;
+    private static cache;
+    private static resolvingStack;
     static resolve<T>(target: new (...args: any[]) => T): T;
+    static teardown(): Promise<void>;
 }
-/**
- * Decorator to mark a class as injectable (Service).
- */
-export declare function Injectable(): (target: any) => void;
-/**
- * Property Decorator: Injects a service.
- */
-export declare function Inject(token: any): (target: any, key: string) => void;

package/dist/util/metadata.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Lightweight Polyfill for Reflect Metadata API.
+ *
+ * Replaces the need for 'reflect-metadata' package to reduce bundle size
+ * while maintaining compatibility with TypeScript's emitDecoratorMetadata.
+ */
+export declare function defineMetadata(key: string | symbol, value: any, target: any, propertyKey?: string | symbol): void;
+export declare function getMetadata(key: string | symbol, target: any, propertyKey?: string | symbol): any;
+declare global {
+    namespace Reflect {
+        function defineMetadata(metadataKey: any, metadataValue: any, target: Object, propertyKey?: string | symbol): void;
+        function getMetadata(metadataKey: any, target: Object, propertyKey?: string | symbol): any;
+        function metadata(metadataKey: any, metadataValue: any): {
+            (target: Function): void;
+            (target: Object, propertyKey: string | symbol): void;
+        };
+    }
+}

package/dist/util/request.d.ts

@@ -18,6 +18,7 @@ declare class ShokupanRequestBase {
     text(): Promise<string>;
     formData(): Promise<FormData>;
     constructor(props: ShokupanRequestProps);
+    clone(): ShokupanRequest<any>;
 }
 /**
  * This type is used to add properties to the request object.

package/dist/util/symbol.d.ts

@@ -29,6 +29,7 @@ export declare const $cachedProtocol: unique symbol;
 export declare const $cachedHost: unique symbol;
 export declare const $cachedOrigin: unique symbol;
 export declare const $cachedQuery: unique symbol;
+export declare const $cachedCookies: unique symbol;
 export declare const $ws: unique symbol;
 export declare const $socket: unique symbol;
 export declare const $io: unique symbol;

package/dist/util/types.d.ts

@@ -3,6 +3,8 @@ import { Server } from 'bun';
 import { Server as NodeServer } from 'node:http';
 import { ConnectOptions, Engines } from 'surrealdb';
 import { ShokupanContext } from '../context';
+import { ServerAdapter } from './adapter';
+import { FileSystemAdapter } from './adapter/filesystem';
 import { $isRouter } from './symbol';
 export type HeadersInit = Headers | Record<string, string> | [string, string][];
 export interface ShokupanPluginOptions {
@@ -118,6 +120,112 @@ export interface CookieOptions {
     sameSite?: boolean | 'lax' | 'strict' | 'none' | 'Lax' | 'Strict' | 'None';
     priority?: 'low' | 'medium' | 'high' | 'Low' | 'Medium' | 'High';
 }
+/**
+ * Helper interface for generic streaming operations.
+ * Provides methods to write data, pipe streams, and handle abort events.
+ */
+export interface StreamHelper {
+    /**
+     * Write data to the stream.
+     * @param data Data to write (Uint8Array or string, strings are auto-encoded to UTF-8)
+     */
+    write(data: Uint8Array | string): Promise<void>;
+    /**
+     * Pipe a ReadableStream to this stream.
+     * @param stream ReadableStream to pipe
+     */
+    pipe(stream: ReadableStream): Promise<void>;
+    /**
+     * Sleep for a specified duration.
+     * @param ms Milliseconds to sleep
+     */
+    sleep(ms: number): Promise<void>;
+    /**
+     * Register a callback to be executed when the stream is aborted.
+     * @param callback Callback function
+     */
+    onAbort(callback: () => void): void;
+}
+/**
+ * Helper interface for text streaming operations.
+ * Provides methods to write text with or without newlines.
+ */
+export interface TextStreamHelper {
+    /**
+     * Write text to the stream without a newline.
+     * @param text Text to write
+     */
+    write(text: string): Promise<void>;
+    /**
+     * Write text to the stream with a newline.
+     * @param text Text to write
+     */
+    writeln(text: string): Promise<void>;
+    /**
+     * Sleep for a specified duration.
+     * @param ms Milliseconds to sleep
+     */
+    sleep(ms: number): Promise<void>;
+    /**
+     * Register a callback to be executed when the stream is aborted.
+     * @param callback Callback function
+     */
+    onAbort(callback: () => void): void;
+}
+/**
+ * Helper interface for Server-Sent Events (SSE) streaming.
+ * Provides methods to write SSE-formatted messages.
+ */
+export interface SSEStreamHelper {
+    /**
+     * Write a Server-Sent Event message.
+     * @param message SSE message with data, event, id, and retry fields
+     */
+    writeSSE(message: SSEMessage): Promise<void>;
+    /**
+     * Sleep for a specified duration.
+     * @param ms Milliseconds to sleep
+     */
+    sleep(ms: number): Promise<void>;
+    /**
+     * Register a callback to be executed when the stream is aborted.
+     * @param callback Callback function
+     */
+    onAbort(callback: () => void): void;
+}
+/**
+ * Server-Sent Event message format.
+ */
+export interface SSEMessage {
+    /**
+     * The data payload of the event.
+     */
+    data: string;
+    /**
+     * Optional event type.
+     */
+    event?: string;
+    /**
+     * Optional event ID.
+     */
+    id?: string;
+    /**
+     * Optional reconnection time in milliseconds.
+     */
+    retry?: number;
+}
+/**
+ * Error handler for stream operations.
+ */
+export type StreamErrorHandler = (err: Error, stream: StreamHelper) => void | Promise<void>;
+/**
+ * Error handler for text stream operations.
+ */
+export type TextStreamErrorHandler = (err: Error, stream: TextStreamHelper) => void | Promise<void>;
+/**
+ * Error handler for SSE stream operations.
+ */
+export type SSEStreamErrorHandler = (err: Error, stream: SSEStreamHelper) => void | Promise<void>;
 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) & {
     originalHandler?: ShokupanHandler<State, Params>;
 };
@@ -129,7 +237,8 @@ export declare enum RouteParamType {
     QUERY = "QUERY",
     HEADER = "HEADER",
     REQUEST = "REQUEST",
-    CONTEXT = "CONTEXT"
+    CONTEXT = "CONTEXT",
+    SERVICE = "SERVICE"
 }
 export interface ServerFactory {
     (options: any): Server<any> | Promise<Server<any>> | NodeServer | Promise<NodeServer>;
@@ -310,6 +419,14 @@ export type ShokupanConfig<T extends Record<string, any> = Record<string, any>>
      * @default false
      */
     enableTracing?: boolean;
+    /**
+     * Query parser mode.
+     * - `extended`: Arrays for duplicate keys (default).
+     * - `simple`: First value only for duplicate keys.
+     * - `strict`: Throws 400 error on duplicate keys.
+     * @default 'extended'
+     */
+    queryParserMode?: 'extended' | 'simple' | 'strict';
     /**
      * JSON parser to use for parsing request bodies.
      *
@@ -407,6 +524,12 @@ export type ShokupanConfig<T extends Record<string, any> = Record<string, any>>
      * @default 30000
      */
     readTimeout: number;
+    /**
+     * Maximum allowed request body size in bytes.
+     * Requests larger than this will be rejected with 413 Payload Too Large.
+     * @default 10485760 (10MB)
+     */
+    maxBodySize?: number;
     /**
      * Timeout for processing the request (milliseconds).
      * Maps to `server.timeout(req, seconds)`.
@@ -433,11 +556,11 @@ export type ShokupanConfig<T extends Record<string, any> = Record<string, any>>
      * The server adapter to use.
      * overrides `serverFactory`.
      */
-    adapter?: 'bun' | 'node' | 'wintercg' | import('./adapter/adapters').ServerAdapter;
+    adapter?: 'bun' | 'node' | 'wintercg' | ServerAdapter;
     /**
      * The file system adapter to use for `ctx.file`.
      */
-    fileSystem?: import('./adapter/filesystem').FileSystemAdapter;
+    fileSystem?: FileSystemAdapter;
     /**
      * Lifecycle hooks.
      */
@@ -509,6 +632,12 @@ export type ShokupanConfig<T extends Record<string, any> = Record<string, any>>
             spec_url: string;
         }>;
     };
+    /**
+     * Configuration for Security Headers.
+     * Can be a boolean to enable/disable defaults, or an object options.
+     * @default true
+     */
+    securityHeaders?: boolean | any;
     /**
      * Any other config options are allowed, but will be ignored.
      * @deprecated