shokupan 0.13.1 → 0.14.0

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

@@ -0,0 +1,59 @@
+export interface QueryOptions {
+    /**
+     * strict equality matches
+     */
+    where?: Record<string, any>;
+    /**
+     * less than matches
+     */
+    lt?: Record<string, number | string>;
+    /**
+     * greater than matches
+     */
+    gt?: Record<string, number | string>;
+    /**
+     * sort results by field
+     */
+    sort?: Record<string, 'asc' | 'desc'>;
+    limit?: number;
+    offset?: number;
+}
+export interface DatastoreAdapter {
+    name: string;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    setupSchema(): Promise<void>;
+    /**
+     * Get a single record by global ID (table + id)
+     */
+    get<T>(table: string, id: string): Promise<T | null>;
+    /**
+     * Create a new record. Fails if exists.
+     */
+    create<T>(table: string, id: string, data: T): Promise<T>;
+    /**
+     * Update an existing record. Fails if not exists.
+     * Merges data.
+     */
+    update<T>(table: string, id: string, data: Partial<T>): Promise<T>;
+    /**
+     * Create or update a record.
+     */
+    upsert<T>(table: string, id: string, data: T): Promise<T>;
+    /**
+     * Delete a single record
+     */
+    delete(table: string, id: string): Promise<void>;
+    /**
+     * Count records matching query
+     */
+    count(table: string, query?: QueryOptions): Promise<number>;
+    /**
+     * Delete multiple records matching query
+     */
+    deleteMany(table: string, query?: QueryOptions): Promise<void>;
+    /**
+     * Find multiple records matching query
+     */
+    findMany<T>(table: string, query?: QueryOptions): Promise<T[]>;
+}

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

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

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

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

package/dist/util/ast-analyzer-worker.d.ts

@@ -0,0 +1,77 @@
+import { EventEmitter } from 'events';
+export type ASTAnalyzerState = 'idle' | 'analyzing' | 'completed' | 'failed';
+export interface ASTAnalyzerResult {
+    applications: any[];
+}
+export interface ASTAnalyzerEvents {
+    'started': () => void;
+    'completed': (result: ASTAnalyzerResult) => void;
+    'failed': (error: Error) => void;
+    'progress': (message: string) => void;
+}
+/**
+ * Worker-based AST analyzer that runs TypeScript analysis in a separate thread.
+ * This prevents blocking the main event loop during intensive AST parsing.
+ */
+export declare class ASTAnalyzerWorker extends EventEmitter {
+    private state;
+    private result;
+    private error;
+    private worker;
+    private analysisPromise;
+    private rootDir;
+    private entrypoint?;
+    private timeout;
+    private startTime;
+    constructor(rootDir: string, entrypoint?: string, timeout?: number);
+    /**
+     * Get the current state of the analyzer.
+     */
+    getState(): ASTAnalyzerState;
+    /**
+     * Get the cached result if analysis completed successfully.
+     */
+    getResult(): ASTAnalyzerResult | null;
+    /**
+     * Get the error if analysis failed.
+     */
+    getError(): Error | null;
+    /**
+     * Check if analysis is currently running.
+     */
+    isAnalyzing(): boolean;
+    /**
+     * Check if analysis has completed successfully.
+     */
+    isCompleted(): boolean;
+    /**
+     * Check if analysis has failed.
+     */
+    isFailed(): boolean;
+    /**
+     * Get analysis duration in milliseconds (if completed or failed).
+     */
+    getDuration(): number | null;
+    /**
+     * Start AST analysis in a worker thread.
+     * Returns immediately and emits events as analysis progresses.
+     */
+    analyze(): Promise<ASTAnalyzerResult>;
+    /**
+     * Wait for analysis to complete (if it's running) or return immediately if already done.
+     */
+    waitForCompletion(): Promise<ASTAnalyzerResult>;
+    /**
+     * Terminate the worker thread if running.
+     */
+    terminate(): void;
+}
+/**
+ * Get or create the global AST analyzer instance.
+ * This ensures all plugins share the same analysis results.
+ */
+export declare function getGlobalAnalyzer(rootDir?: string, entrypoint?: string, timeout?: number): ASTAnalyzerWorker;
+/**
+ * Reset the global analyzer instance (useful for testing).
+ */
+export declare function resetGlobalAnalyzer(): void;

package/dist/util/ast-worker-thread.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,6 @@
+/**
+ * Fast Cookie Parser
+ *
+ * Optimized for speed by minimizing allocations and avoiding regex/split.
+ */
+export declare function parseCookies(str: string): Record<string, string>;

package/dist/util/env-loader.d.ts

@@ -1,3 +1,4 @@
+import { Logger } from './logger';
 export type EnvLoaderOptions = {
     /**
      * If provided, k8s secrets will be loaded from the given paths
@@ -9,6 +10,10 @@ export type EnvLoaderOptions = {
      * @default []
      */
     k8sConfigMapMountPaths?: string[];
+    /**
+     * Optional logger instance
+     */
+    logger?: Logger;
 };
 type Listener<T> = (value: T) => void;
 /**
@@ -50,6 +55,7 @@ declare const $secretSubjects: unique symbol;
 declare const $options: unique symbol;
 declare const $watchers: unique symbol;
 declare const $watchersStarted: unique symbol;
+declare const $logger: unique symbol;
 declare const $getSecretValueInternal: unique symbol;
 declare const $getOrCreateSubject: unique symbol;
 declare const $loadSecrets: unique symbol;
@@ -65,6 +71,7 @@ export declare abstract class EnvLoader {
     private [$options];
     private [$watchers];
     private [$watchersStarted];
+    private [$logger];
     constructor(options?: EnvLoaderOptions);
     /**
      * Initialize the loader: read secrets.

package/dist/util/html.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Escapes unsafe characters in a string for use in HTML using named character references.
+ *
+ * @param unsafe - The input value to escape. If not a string, it will be coerced to one.
+ * @returns The escaped string.
+ */
+export declare function escapeHtml(unsafe: unknown): string;
+/**
+ * Safely serializes data to JSON for embedding in a <script> tag.
+ * Prevents Script Injection via </script> tags.
+ *
+ * @param data - The data to serialize.
+ * @returns The JSON string with </script> escaped.
+ */
+export declare function safeScriptJson(data: any): string;

package/dist/util/ide.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Utility for generating links to open files in various editors.
+ * Controlled by the `IDE` environment variable or app-level configuration.
+ */
+export declare function configureIde(config: {
+    ide?: string;
+}): void;
+export declare function getEditorLinkPattern(): string;
+export declare function generateEditorLink(filePath: string, line?: number, column?: number): string;

package/dist/util/logger.d.ts

@@ -0,0 +1,25 @@
+export interface Logger {
+    debug(module: string, msg: string, props?: Record<string, any>): void;
+    info(module: string, msg: string, props?: Record<string, any>): void;
+    warn(module: string, msg: string, props?: Record<string, any>): void;
+    error(module: string, msg: string, props?: Record<string, any>): void;
+    fatal(module: string, msg: string, props?: Record<string, any>): void;
+}
+export declare class JsonLogger implements Logger {
+    private write;
+    debug(module: string, msg: string, props?: Record<string, any>): void;
+    info(module: string, msg: string, props?: Record<string, any>): void;
+    warn(module: string, msg: string, props?: Record<string, any>): void;
+    error(module: string, msg: string, props?: Record<string, any>): void;
+    fatal(module: string, msg: string, props?: Record<string, any>): void;
+}
+export declare class ConsolaLogger implements Logger {
+    private consola;
+    constructor(level?: number);
+    debug(module: string, msg: string, props?: Record<string, any>): void;
+    info(module: string, msg: string, props?: Record<string, any>): void;
+    warn(module: string, msg: string, props?: Record<string, any>): void;
+    error(module: string, msg: string, props?: Record<string, any>): void;
+    fatal(module: string, msg: string, props?: Record<string, any>): void;
+}
+export declare function createLogger(env?: string): Logger;

package/dist/util/query-string.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Fast Querystring Parser
+ *
+ * Optimized for speed by minimizing allocations and avoiding regex.
+ * Benchmarked faster than 'fast-querystring' and significantly faster than native 'URLSearchParams'.
+ */
+export type QueryParserMode = 'simple' | 'extended' | 'strict';
+export declare function parseQuery(url: string, mode?: QueryParserMode): Record<string, any>;

package/dist/util/response-transformer.d.ts

@@ -0,0 +1,87 @@
+import { BodyInit } from 'bun';
+/**
+ * Response transformer function
+ * Converts data to a specific format and returns response metadata
+ */
+export interface ResponseTransformer {
+    /**
+     * MIME type(s) this transformer handles
+     * Can be a string or array of strings
+     */
+    contentType: string | string[];
+    /**
+     * Serialize the data
+     * @param data The data to serialize
+     * @returns Serialized body and optional headers
+     */
+    serialize: (data: any) => {
+        body: BodyInit;
+        headers?: Record<string, string>;
+    } | Promise<{
+        body: BodyInit;
+        headers?: Record<string, string>;
+    }>;
+    /**
+     * Optional: Quality value for content negotiation (0-1)
+     * Higher values = preferred format when multiple matches exist
+     */
+    quality?: number;
+}
+/**
+ * Response transformer registry
+ * Manages registered transformers and performs content negotiation
+ */
+export declare class ResponseTransformerRegistry {
+    private transformers;
+    private defaultTransformer?;
+    /**
+     * Register a response transformer
+     * @param transformer The transformer to register
+     */
+    register(transformer: ResponseTransformer): void;
+    /**
+     * Get a transformer by exact content type match
+     * @param contentType The content type to look up
+     * @returns The transformer or undefined
+     */
+    getTransformer(contentType: string): ResponseTransformer | undefined;
+    /**
+     * Set the default transformer content type
+     * @param contentType The content type to use as default
+     */
+    setDefault(contentType: string): void;
+    /**
+     * Get the default transformer
+     * @returns The default transformer or undefined
+     */
+    getDefault(): ResponseTransformer | undefined;
+    /**
+     * Perform content negotiation based on Accept header
+     * @param acceptHeader The Accept header value
+     * @returns The best matching transformer or undefined
+     */
+    negotiate(acceptHeader: string): ResponseTransformer | undefined;
+    /**
+     * Parse Accept header into structured entries
+     * @param acceptHeader The Accept header value
+     * @returns Array of parsed accept entries
+     */
+    private parseAcceptHeader;
+    /**
+     * Find exact content type match
+     * @param accept The accept entry to match
+     * @returns The matching transformer or undefined
+     */
+    private findExactMatch;
+    /**
+     * Find wildcard content type match
+     * @param accept The accept entry to match
+     * @returns The matching transformer or undefined
+     */
+    private findWildcardMatch;
+    /**
+     * Get all registered content types
+     * @returns Array of registered content types
+     */
+    getRegisteredTypes(): string[];
+}

package/dist/util/symbol.d.ts

@@ -14,6 +14,7 @@ export declare const $mountPath: unique symbol;
 export declare const $dispatch: unique symbol;
 export declare const $routes: unique symbol;
 export declare const $routeSpec: unique symbol;
+export declare const $controllerHooks: unique symbol;
 export declare const $url: unique symbol;
 export declare const $requestId: unique symbol;
 export declare const $debug: unique symbol;

package/dist/util/types.d.ts

@@ -1,10 +1,10 @@
 import { OpenAPI } from '@scalar/openapi-types';
 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 { Logger } from './logger';
 import { $isRouter } from './symbol';
 export type HeadersInit = Headers | Record<string, string> | [string, string][];
 export interface ShokupanPluginOptions {
@@ -43,6 +43,39 @@ type ParsePathParams<Path extends string> = Path extends `${infer _Start}:${infe
     [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>;
+/**
+ * Type guard to check if a state property exists and narrow its type.
+ *
+ * @example
+ * ```typescript
+ * if (hasStateProperty(ctx, 'userId')) {
+ *     // ctx.state.userId is now typed as defined (not undefined)
+ *     console.log(ctx.state.userId);
+ * }
+ * ```
+ */
+export declare function hasStateProperty<S extends Record<string, any>, K extends string>(state: S, key: K): key is K & keyof S;
+/**
+ * Runtime assertion that a state property exists.
+ * Throws an error if the property is missing.
+ *
+ * @example
+ * ```typescript
+ * requireStateProperty(ctx.state, 'userId');
+ * // Now TypeScript knows ctx.state.userId exists
+ * const id = ctx.state.userId;
+ * ```
+ */
+export declare function requireStateProperty<S extends Record<string, any>, K extends keyof S>(state: S, key: K, message?: string): asserts state is S & Record<K, NonNullable<S[K]>>;
+/**
+ * Type-safe state getter with optional default value.
+ *
+ * @example
+ * ```typescript
+ * const userId = getStateProperty(ctx.state, 'userId', 'anonymous');
+ * ```
+ */
+export declare function getStateProperty<S extends Record<string, any>, K extends keyof S, D = undefined>(state: S, key: K, defaultValue?: D): S[K] | D;
 export interface RouteMetadata {
     file: string;
     line: number;
@@ -243,6 +276,9 @@ export declare enum RouteParamType {
 export interface ServerFactory {
     (options: any): Server<any> | Promise<Server<any>> | NodeServer | Promise<NodeServer>;
 }
+export interface ErrorHandler<T = any> {
+    (err: T, ctx: ShokupanContext): Response | Promise<Response>;
+}
 export type NextFn = () => Promise<any>;
 export type Middleware = ((ctx: ShokupanContext<unknown>, next: NextFn) => Promise<any> | any) & {
     isBuiltin?: boolean;
@@ -357,6 +393,10 @@ export type ShokupanRoute = {
      * Middleware stack metadata for this route (Controller/Method level)
      */
     middleware?: Middleware[];
+    /**
+     * Whether this route is a WebSocket route
+     */
+    isSocket?: boolean;
 };
 export type ShokupanConfig<T extends Record<string, any> = Record<string, any>> = Partial<{
     /**
@@ -412,6 +452,18 @@ export type ShokupanConfig<T extends Record<string, any> = Record<string, any>>
      * @default true
      */
     blockOnAsyncApiGen: boolean;
+    /**
+     * Whether to use async AST scanning with worker threads.
+     * When enabled, AST analysis runs in a separate thread to avoid blocking server startup.
+     * @default true
+     */
+    enableAsyncAstScanning?: boolean;
+    /**
+     * Maximum time (ms) to wait for AST analysis before timing out.
+     * Only applies when enableAsyncAstScanning is true.
+     * @default 30000 (30 seconds)
+     */
+    astAnalysisTimeout?: number;
     /**
      * Whether to reuse the port.
      * @default false
@@ -461,6 +513,20 @@ export type ShokupanConfig<T extends Record<string, any> = Record<string, any>>
      * @default 60
      */
     autoBackpressureLevel?: number;
+    /**
+     * Whether to enable automatic content negotiation for ctx.json() and other response methods.
+     * When enabled, ctx.json() will use the response transformer registry to negotiate the best
+     * response format based on the Accept header.
+     * @default false
+     */
+    enableAutoContentNegotiation?: boolean;
+    /**
+     * Default response transformer content type.
+     * If set, ctx.respond() and auto-negotiated ctx.json() will use this transformer
+     * when no Accept header matches or when Accept is any.
+     * @default 'application/json'
+     */
+    defaultResponseTransformer?: string;
     /**
      * Whether to enable middleware and handler tracking.
      * When enabled, `ctx.handlerStack` will be populated with the handlers the request has passed through.
@@ -479,15 +545,15 @@ export type ShokupanConfig<T extends Record<string, any> = Record<string, any>>
      * This enables websocket messages to run through the HTTP server.
      * e.g.
      * ```json
-     * {
-     *  "method": "POST",
-     *  "path": "/api/v1/myHttpEndpoint",
-     *  "headers": {},
-     *  "body": {
+        * {
+        *  "method": "POST",
+        *  "path": "/api/v1/myHttpEndpoint",
+        *  "headers": {},
+        *  "body": {
      *      "type": "text",
-     *      "data": "Hello, world!"
+        *      "data": "Hello, world!"
      *  }
-     * }
+        * }
      * ```
      * @default false
      */
@@ -515,17 +581,7 @@ export type ShokupanConfig<T extends Record<string, any> = Record<string, any>>
     /**
      * Logger object.
      */
-    logger: {
-        verbose: boolean;
-        info: (msg: string, props: Record<string, any>) => void;
-        debug: (msg: string, props: Record<string, any>) => void;
-        warning: (msg: string, props: Record<string, any>) => void;
-        error: (msg: string, props: Record<string, any>) => void;
-        /**
-         * Something fatally went wrong and the application cannot continue.
-         */
-        fatal: (msg: string, props: Record<string, any>) => void;
-    };
+    logger: Logger;
     /**
      * Timeout for reading the request body (milliseconds).
      * Maps to Bun's `idleTimeout`.
@@ -564,7 +620,7 @@ export type ShokupanConfig<T extends Record<string, any> = Record<string, any>>
      * The server adapter to use.
      * overrides `serverFactory`.
      */
-    adapter?: 'bun' | 'node' | 'wintercg' | ServerAdapter;
+    adapter?: 'bun' | 'node' | 'wintercg' | 'h3' | ServerAdapter;
     /**
      * The file system adapter to use for `ctx.file`.
      */
@@ -579,31 +635,19 @@ export type ShokupanConfig<T extends Record<string, any> = Record<string, any>>
      */
     validateStatusCodes: boolean;
     /**
-     * Configuration for SurrealDB.
+     * @deprecated Use `datastore` config instead.
      */
-    surreal?: {
-        /**
-         * SurrealDB engines.
-         * @default Embedded
-         */
-        engines?: Engines;
-        /**
-         * SurrealDB connection URL.
-         * @default 'rocksdb://database'
-         */
-        url?: string;
-        /**
-         * SurrealDB connection options.
-         */
-        connectOptions?: ConnectOptions;
-        /**
-         * SurrealDB namespace.
-         */
-        namespace?: string;
+    surreal?: any;
+    datastore?: {
+        adapter: 'surreal' | 'sqlite' | 'level' | 'knex';
         /**
-         * SurrealDB database.
+         * Options for the specific adapter.
+         * - For 'surreal', this matches SurrealAdapterOptions
+         * - For 'sqlite', this matches SqliteAdapterOptions
+         * - For 'level', this matches LevelAdapterOptions
+         * - For 'knex', this matches KnexAdapterOptions (Knex.Config)
          */
-        database?: string;
+        options?: any;
     };
     /**
      * Configuration for the AI Plugin manifest (.well-known/ai-plugin.json).
@@ -651,6 +695,18 @@ export type ShokupanConfig<T extends Record<string, any> = Record<string, any>>
      * @deprecated
      */
     [key: string]: any;
+    /**
+     * IDE configuration for file links.
+     * Can be a specific editor name (vscode, intellij, etc.) or an autodetection mode.
+     * Overrides process.env.IDE.
+     *
+     * Options:
+     * - 'vscode', 'vscode-insiders', 'vscodium', 'cursor', 'intellij', 'sublime', 'neovim'
+     * - 'vscode.dev': Force generic vscode.dev links
+     * - 'autodetect-vscode.dev': Auto-detect git remote and generate specific vscode.dev links
+     * - 'autodetect-repo': Auto-detect git remote and generate web repository links
+     */
+    ide?: string;
 }>;
 export interface RequestOptions {
     path?: string;
@@ -717,5 +773,23 @@ export interface StaticServeOptions<T extends Record<string, any>> {
      * OpenAPI specification for the static route.
      */
     openapi?: MethodAPISpec;
+    /**
+     * Enable ETags for static files.
+     */
+    etag?: boolean;
+    /**
+     * Maximum age for the cache.
+     */
+    maxAge?: number;
+    /**
+     * Whether the file is immutable.
+     * maxAge must be set to a value > 0 for this to have any effect.
+     */
+    immutable?: boolean;
+    /**
+     * Whether to use the cache.
+     * @default true
+     */
+    useCache?: boolean;
 }
 export {};