shokupan 0.11.0 → 0.13.0

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,42 @@ 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;
+/**
+ * Decorator: Registers a method as an MCP Tool.
+ * @param name The name of the tool (defaults to method name if not provided)
+ * @param description Optional description
+ * @param inputSchema Optional JSON Schema for input arguments
+ */
+export declare function Tool(options?: {
+    name?: string;
+    description?: string;
+    inputSchema?: any;
+}): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+/**
+ * Decorator: Registers a method as an MCP Prompt.
+ * @param name The name of the prompt
+ * @param description Optional description
+ * @param args Optional list of arguments
+ */
+export declare function Prompt(options?: {
+    name?: string;
+    description?: string;
+    arguments?: {
+        name: string;
+        description?: string;
+        required?: boolean;
+    }[];
+}): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+/**
+ * Decorator: Registers a method as an MCP Resource handler.
+ * @param uri The URI pattern for the resource
+ * @param name Optional name
+ * @param description Optional description
+ * @param mimeType Optional MIME type
+ */
+export declare function Resource(uri: string, options?: {
+    name?: string;
+    description?: string;
+    mimeType?: string;
+}): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => 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/env-loader.d.ts

@@ -0,0 +1,99 @@
+export type EnvLoaderOptions = {
+    /**
+     * If provided, k8s secrets will be loaded from the given paths
+     * @default []
+     */
+    k8sSecretMountPaths?: string[];
+    /**
+     * If provided, k8s config maps will be loaded from the given paths
+     * @default []
+     */
+    k8sConfigMapMountPaths?: string[];
+};
+type Listener<T> = (value: T) => void;
+/**
+ * A subject that emits values to listeners.
+ *
+ * This is used to emit values to listeners when they change.
+ */
+export declare class EmitterSubject<T> {
+    private _value;
+    private _listeners;
+    constructor(initialValue: T);
+    get value(): T;
+    next(newValue: T): void;
+    subscribe(callback: Listener<T>): {
+        unsubscribe: () => void;
+    };
+    toString(): string;
+    toJSON(): string;
+}
+/**
+ * Extend this class with a class of your own. The extended class static properties will then
+ * be dynamically loaded from environment variables (additionally .env files).
+ * Values will be trimmed then parsed to the type of the property.
+ *
+ * Secrets should be loaded using the getSecret method -- this prevents them from being logged
+ * or otherwise leaked, and enables the use of environment variables to load secrets from
+ * k8s secrets, vault, etc.
+ *
+ * ```typescript
+ * class myEnv extends EnvLoader {
+ *     readonly prop = 123; // loads env variable PROP or PROP (mapped)
+ *     readonly prop_time = 123; // loads env variable PROP_TIME
+ *     readonly propTime = 123; // loads env variable PROP_TIME
+ * }
+ * ```
+ */
+declare const $secretsCache: unique symbol;
+declare const $secretSubjects: unique symbol;
+declare const $options: unique symbol;
+declare const $watchers: unique symbol;
+declare const $watchersStarted: unique symbol;
+declare const $getSecretValueInternal: unique symbol;
+declare const $getOrCreateSubject: unique symbol;
+declare const $loadSecrets: unique symbol;
+declare const $setupWatchers: unique symbol;
+declare const $updateSubject: unique symbol;
+declare const $updateMappedProperty: unique symbol;
+declare const $mapProperties: unique symbol;
+declare const $assignProperty: unique symbol;
+declare const $toSnakeCase: unique symbol;
+export declare abstract class EnvLoader {
+    private [$secretsCache];
+    private [$secretSubjects];
+    private [$options];
+    private [$watchers];
+    private [$watchersStarted];
+    constructor(options?: EnvLoaderOptions);
+    /**
+     * Initialize the loader: read secrets.
+     * This must be called after the constructor.
+     */
+    init(): Promise<void>;
+    /**
+     * Loads a secret from the environment asynchronously.
+     */
+    getSecret(key: string): Promise<string | undefined>;
+    getSecret(key: string, observer: true): Promise<EmitterSubject<string | undefined>>;
+    /**
+     * Loads a secret from the environment synchronously.
+     */
+    getSecretSync(key: string): string | undefined;
+    getSecretSync(key: string, observer: true): EmitterSubject<string | undefined>;
+    /**
+     * Loads a variable from the environment synchronously.
+     */
+    getVar(key: string): string | undefined;
+    getVar(key: string, observer: true): EmitterSubject<string | undefined>;
+    private [$getSecretValueInternal];
+    private [$getOrCreateSubject];
+    private [$loadSecrets];
+    private [$setupWatchers];
+    private [$updateSubject];
+    private [$updateMappedProperty];
+    private [$mapProperties];
+    private [$assignProperty];
+    private [$toSnakeCase];
+}
+export {};

package/dist/util/mcp-protocol.d.ts

@@ -0,0 +1,52 @@
+export interface JsonRpcRequest {
+    jsonrpc: "2.0";
+    id?: string | number | null;
+    method: string;
+    params?: any;
+}
+export interface JsonRpcResponse {
+    jsonrpc: "2.0";
+    id: string | number | null;
+    result?: any;
+    error?: {
+        code: number;
+        message: string;
+        data?: any;
+    };
+}
+export interface McpTool {
+    name: string;
+    description?: string;
+    inputSchema?: any;
+    handler: (args: any) => Promise<any> | any;
+}
+export interface McpPrompt {
+    name: string;
+    description?: string;
+    arguments?: {
+        name: string;
+        description?: string;
+        required?: boolean;
+    }[];
+    handler: (args: any) => Promise<any> | any;
+}
+export interface McpResource {
+    uri: string;
+    name?: string;
+    description?: string;
+    mimeType?: string;
+    handler: (uri: string, args?: any) => Promise<any> | any;
+}
+export declare class McpProtocol {
+    private tools;
+    private prompts;
+    private resources;
+    constructor(tools?: McpTool[], prompts?: McpPrompt[], resources?: McpResource[]);
+    addTool(tool: McpTool): void;
+    addPrompt(prompt: McpPrompt): void;
+    addResource(resource: McpResource): void;
+    merge(other: McpProtocol): void;
+    handleMessage(message: JsonRpcRequest): Promise<JsonRpcResponse | null>;
+    private success;
+    private error;
+}

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/promise.d.ts

@@ -0,0 +1,16 @@
+import { RequestContextStore } from './async-hooks';
+export declare const kContext: unique symbol;
+export interface PatchedPromise extends Promise<any> {
+    [kContext]?: {
+        store?: RequestContextStore;
+        stack: string;
+    };
+}
+/**
+ * Monkeypatches the global Promise constructor to attach the current AsyncLocalStorage store
+ * and a snapshot of the stack trace to every new Promise instance.
+ *
+ * This enables the application to trace unhandled rejections back to the original request
+ * and see where the dangling promise was created.
+ */
+export declare function enablePromisePatch(): 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,11 @@ 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;
+export declare const $mcpTools: unique symbol;
+export declare const $mcpPrompts: unique symbol;
+export declare const $mcpResources: unique symbol;
+export declare const $resilienceConfig: 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>;
@@ -276,6 +385,14 @@ export type ShokupanConfig<T extends Record<string, any> = Record<string, any>>
      * @default true
      */
     enableOpenApiGen: boolean;
+    /**
+     * Whether to enable monkeypatching of the global Promise constructor.
+     * When enabled, Promises created within an async context will carry that context
+     * (including `requestId`) and the creation stack trace. This increases memory and
+     * cpu usage, but provides richer logging for unhandled rejections.
+     * @default false
+     */
+    enablePromiseMonkeypatch: boolean;
     /**
      * Whether to block server startup until OpenAPI generation completes.
      * Only applies when enableOpenApiGen is true.
@@ -310,6 +427,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 +532,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 +564,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 +640,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 false
+     */
+    defaultSecurityHeaders?: boolean | any;
     /**
      * Any other config options are allowed, but will be ignored.
      * @deprecated

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "shokupan",
-    "version": "0.11.0",
+    "version": "0.13.0",
     "description": "Shokupan is a low-lift modern web framework for Bun.",
     "author": "Andrew G. Knackstedt",
     "publishConfig": {
@@ -23,6 +23,7 @@
     "type": "module",
     "scripts": {
         "dev": "bun --watch --inspect examples/full/main.ts",
+        "mcp:inspector": "npx @modelcontextprotocol/inspector http://localhost:8372/mcp",
         "debug:otel": "sh scripts/debug-otel.sh",
         "docs": "cd docs && bun run dev",
         "build": "vite build",
@@ -58,21 +59,16 @@
     },
     "dependencies": {
         "@clack/prompts": "^0.11.0",
-        "@opentelemetry/api": "^1.9.0",
-        "@opentelemetry/exporter-trace-otlp-proto": "^0.208.0",
-        "@opentelemetry/resources": "^2.3.0",
-        "@opentelemetry/sdk-trace-base": "^2.3.0",
-        "@opentelemetry/sdk-trace-node": "^2.3.0",
-        "@opentelemetry/semantic-conventions": "^1.38.0",
-        "@scalar/openapi-types": "^0.5.3",
-        "js-yaml": "^4.1.1",
+        "cockatiel": "^3.2.1",
         "nanoid": "^5.1.6",
-        "socket.io": "^4.8.3",
         "tslib": "^2.8.1"
     },
     "peerDependencies": {
         "@apollo/server": "^5.2.0",
+        "@modelcontextprotocol/sdk": "^1.25.2",
+        "@opentelemetry/api": "^1.9.0",
         "@scalar/api-reference": "^1.0.0",
+        "@scalar/openapi-types": "^0.5.3",
         "@surrealdb/node": "^2.4.0",
         "ajv": "^8.0.0",
         "ajv-formats": "^3.0.0",
@@ -83,9 +79,11 @@
         "graphql": "^16.12.0",
         "graphql-yoga": "^5.18.0",
         "jose": "^6.0.0",
+        "js-yaml": "^4.1.1",
         "parse-json": "^8.0.0",
         "reflect-metadata": "^0.2.0",
         "secure-json-parse": "^4.0.0",
+        "socket.io": "^4.8.3",
         "surrealdb": "^2.0.0-alpha.16"
     },
     "peerDependenciesMeta": {
@@ -136,11 +134,38 @@
         },
         "surrealdb": {
             "optional": true
+        },
+        "@modelcontextprotocol/sdk": {
+            "optional": true
+        },
+        "@opentelemetry/api": {
+            "optional": true
+        },
+        "@scalar/openapi-types": {
+            "optional": true
+        },
+        "js-yaml": {
+            "optional": true
+        },
+        "socket.io": {
+            "optional": true
+        },
+        "youch": {
+            "optional": true
         }
     },
     "devDependencies": {
         "@apollo/server": "^5.2.0",
+        "@modelcontextprotocol/sdk": "^1.25.2",
+        "@opentelemetry/api": "^1.9.0",
+        "@opentelemetry/exporter-trace-otlp-proto": "^0.208.0",
+        "@opentelemetry/resources": "^2.3.0",
+        "@opentelemetry/sdk-trace-base": "^2.3.0",
+        "@opentelemetry/sdk-trace-node": "^2.3.0",
+        "@opentelemetry/semantic-conventions": "^1.38.0",
         "@scalar/api-reference": "^1.0.0",
+        "@scalar/openapi-types": "^0.5.3",
+        "@sentry/node": "^10.36.0",
         "@sinclair/typebox": "^0.34.47",
         "@surrealdb/node": "^2.4.0",
         "@tsconfig/bun": "^1.0.10",
@@ -161,11 +186,13 @@
         "graphql": "^16.12.0",
         "graphql-yoga": "^5.18.0",
         "jose": "^6.0.0",
+        "js-yaml": "^4.1.1",
         "parse-json": "^8.0.0",
         "preact": "^10.28.2",
         "preact-render-to-string": "^6.6.5",
         "reflect-metadata": "^0.2.0",
         "secure-json-parse": "^4.0.0",
+        "socket.io": "^4.8.3",
         "supertest": "^7.2.2",
         "surrealdb": "^2.0.0-alpha.14",
         "typescript": "~5.9.3",