shokupan 0.13.0 → 0.14.0

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 {};

package/dist/websocket.d.ts

@@ -0,0 +1,163 @@
+import { ServerWebSocket } from 'bun';
+import { ShokupanContext } from './context';
+import { $childControllers, $childRouters, $routes } from './util/symbol';
+/**
+ * WebSocket lifecycle handlers
+ */
+export interface WebSocketHandlers<T = any> {
+    /**
+     * Called when HTTP upgrade request is received (before WebSocket connection).
+     * Return false to reject the upgrade.
+     */
+    onUpgrade?: (ctx: ShokupanContext<T>) => boolean | void | Promise<boolean | void>;
+    /**
+     * Called after WebSocket connection is established.
+     * Return value is automatically set to both ws.data and ctx.state.
+     */
+    onOpen?: (ctx: ShokupanContext<T>, ws: ServerWebSocket<any>) => any | Promise<any>;
+    /**
+     * Called before routing to event handlers.
+     * Return false or throw to prevent event routing.
+     */
+    onEvent?: (ctx: ShokupanContext<T>, ws: ServerWebSocket<any>, event: string, data: any) => boolean | void | Promise<boolean | void>;
+    /**
+     * Called for every message (before event parsing/routing).
+     */
+    onMessage?: (ctx: ShokupanContext<T>, ws: ServerWebSocket<any>, message: string | Buffer) => void | Promise<void>;
+    /**
+     * Called when WebSocket connection is closed.
+     */
+    onClose?: (ctx: ShokupanContext<T>, ws: ServerWebSocket<any>, code?: number, reason?: string) => void | Promise<void>;
+    /**
+     * Called when an error occurs.
+     */
+    onError?: (ctx: ShokupanContext<T>, ws: ServerWebSocket<any>, error: Error) => void | Promise<void>;
+}
+/**
+ * Event handler function
+ */
+export type EventHandler<T = any> = (ctx: ShokupanContext<T>, data?: any) => void | Promise<void>;
+/**
+ * WebSocket Router for organizing WebSocket endpoints.
+ *
+ * Provides lifecycle hooks and event-based message routing.
+ *
+ * @example
+ * ```ts
+ * const wsRouter = new ShokupanWebsocketRouter();
+ *
+ * wsRouter.onUpgrade((ctx) => {
+ *   if (!ctx.get("authorization")) return false;
+ *   return true;
+ * });
+ *
+ * wsRouter.onOpen((ctx, ws) => {
+ *   return { userId: "123" }; // Sets ws.data and ctx.state
+ * });
+ *
+ * wsRouter.event("chat.message", (ctx, data) => {
+ *   ctx.broadcast("chat.message", data);
+ * });
+ *
+ * app.mount('/ws', wsRouter);
+ * ```
+ */
+export declare class ShokupanWebsocketRouter<T = any> {
+    private handlers;
+    middleware: any[];
+    private events;
+    /**
+     * Register upgrade validation handler.
+     * Called when HTTP upgrade request is received.
+     * Return false to reject the upgrade.
+     */
+    onUpgrade(handler: NonNullable<WebSocketHandlers<T>['onUpgrade']>): this;
+    /**
+     * Register open handler.
+     * Called after WebSocket connection is established.
+     * Return value is automatically set to both ws.data and ctx.state.
+     */
+    onOpen(handler: NonNullable<WebSocketHandlers<T>['onOpen']>): this;
+    /**
+     * Register event middleware handler.
+     * Called before routing to specific event handlers.
+     * Return false or throw to prevent event routing.
+     */
+    onEvent(handler: NonNullable<WebSocketHandlers<T>['onEvent']>): this;
+    /**
+     * Register message handler.
+     * Called for every message before event parsing/routing.
+     */
+    onMessage(handler: NonNullable<WebSocketHandlers<T>['onMessage']>): this;
+    /**
+     * Register close handler.
+     * Called when WebSocket connection is closed.
+     */
+    onClose(handler: NonNullable<WebSocketHandlers<T>['onClose']>): this;
+    /**
+     * Register error handler.
+     * Called when an error occurs.
+     */
+    onError(handler: NonNullable<WebSocketHandlers<T>['onError']>): this;
+    /**
+     * Register an event handler.
+     *
+     * @param name - Event name
+     * @param handler - Handler function
+     *
+     * @example
+     * ```ts
+     * router.event("chat.message", (ctx, data) => {
+     *   ctx.broadcast("chat.message", data);
+     * });
+     * ```
+     */
+    event(name: string, handler: EventHandler<T>): this;
+    /**
+     * Get registered handlers.
+     * @internal
+     */
+    getHandlers(): WebSocketHandlers<T>;
+    /**
+     * Get registered events.
+     * @internal
+     */
+    getEvents(): Map<string, EventHandler<T>>;
+    /**
+     * Get registered event handlers.
+     * @internal
+     */
+    getEventHandlers(): Map<string, EventHandler<T>[]>;
+    /**
+     * Get child routers (always empty for WebSocket router).
+     * @internal
+     */
+    get [$childRouters](): any[];
+    /**
+     * Get local routes (always empty for WebSocket router as it handles its own routing).
+     * @internal
+     */
+    get [$routes](): any[];
+    /**
+     * Get child controllers (always empty).
+     * @internal
+     */
+    get [$childControllers](): any[];
+    getRoutes(): any[];
+    /**
+     * Registry Accessor to support Dashboard Graph
+     */
+    get registry(): {
+        metadata: any;
+        middleware: any[];
+        routes: any[];
+        routers: any[];
+        controllers: any[];
+        events: any[];
+    };
+    /**
+     * Check if this is a WebSocket router instance.
+     * @internal
+     */
+    static isWebSocketRouter(obj: any): obj is ShokupanWebsocketRouter;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "shokupan",
-    "version": "0.13.0",
+    "version": "0.14.0",
     "description": "Shokupan is a low-lift modern web framework for Bun.",
     "author": "Andrew G. Knackstedt",
     "publishConfig": {
@@ -60,6 +60,8 @@
     "dependencies": {
         "@clack/prompts": "^0.11.0",
         "cockatiel": "^3.2.1",
+        "consola": "^3.4.2",
+        "mrmime": "^2.0.1",
         "nanoid": "^5.1.6",
         "tslib": "^2.8.1"
     },
@@ -78,12 +80,15 @@
         "eta": "^4.0.0",
         "graphql": "^16.12.0",
         "graphql-yoga": "^5.18.0",
+        "h3": "^2.0.0",
         "jose": "^6.0.0",
         "js-yaml": "^4.1.1",
+        "knex": "^3.1.0",
         "parse-json": "^8.0.0",
         "reflect-metadata": "^0.2.0",
         "secure-json-parse": "^4.0.0",
         "socket.io": "^4.8.3",
+        "sqlite3": "^5.1.7",
         "surrealdb": "^2.0.0-alpha.16"
     },
     "peerDependenciesMeta": {
@@ -108,6 +113,9 @@
         "graphql-yoga": {
             "optional": true
         },
+        "h3": {
+            "optional": true
+        },
         "class-validator": {
             "optional": true
         },
@@ -117,6 +125,9 @@
         "jose": {
             "optional": true
         },
+        "knex": {
+            "optional": true
+        },
         "parse-json": {
             "optional": true
         },
@@ -150,6 +161,9 @@
         "socket.io": {
             "optional": true
         },
+        "sqlite3": {
+            "optional": true
+        },
         "youch": {
             "optional": true
         }
@@ -174,10 +188,12 @@
         "@types/js-yaml": "^4.0.9",
         "@types/node": "^25.0.6",
         "@types/supertest": "^6.0.3",
+        "abstract-level": "^3.1.1",
         "ajv": "^8.0.0",
         "ajv-formats": "^3.0.0",
         "arctic": "^3.0.0",
         "axios": "^1.13.2",
+        "better-sqlite3": "^12.6.2",
         "class-transformer": "^0.5.0",
         "class-validator": "^0.14.0",
         "eta": "^4.0.0",
@@ -185,16 +201,26 @@
         "get-port": "^7.1.0",
         "graphql": "^16.12.0",
         "graphql-yoga": "^5.18.0",
+        "h3": "2.0.1-rc.11",
         "jose": "^6.0.0",
         "js-yaml": "^4.1.1",
+        "knex": "^3.1.0",
+        "memory-level": "^3.1.0",
+        "mysql": "^2.18.1",
+        "mysql2": "^3.16.2",
+        "oracledb": "^6.10.0",
         "parse-json": "^8.0.0",
+        "pg": "^8.17.2",
+        "pg-query-stream": "^4.11.2",
         "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",
+        "sqlite3": "^5.1.7",
         "supertest": "^7.2.2",
         "surrealdb": "^2.0.0-alpha.14",
+        "tedious": "^19.2.0",
         "typescript": "~5.9.3",
         "valibot": "^1.2.0",
         "vite": "^7.3.1",

package/dist/analyzer-B0fMzeIo.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"analyzer-B0fMzeIo.js","sources":["../src/plugins/application/openapi/analyzer.ts"],"sourcesContent":["\n// Re-export types used in public API\nexport type { ApplicationInstance, RouteInfo } from './analyzer.impl';\nimport type { ApplicationInstance } from './analyzer.impl';\n\n/**\n * OpenAPI Analyzer Wrapper.\n * \n * This class wraps the actual OpenAPIAnalyzer implementation to facilitate\n * lazy loading of the 'typescript' peer dependency. The actual implementation\n * and the 'typescript' module are only loaded when `analyze()` is called.\n */\nexport class OpenAPIAnalyzer {\n    private analyzerImpl: any;\n\n    constructor(private rootDir: string, private entrypoint?: string) { }\n\n    /**\n     * Main analysis entry point.\n     * Dynamically imports the implementation and runs the analysis.\n     */\n    public async analyze(): Promise<{ applications: ApplicationInstance[]; }> {\n        // Dynamic import to avoid loading 'typescript' peer dependency if not needed (e.g. at runtime)\n        const { OpenAPIAnalyzer: AnalyzerImpl } = await import('./analyzer.impl');\n        this.analyzerImpl = new AnalyzerImpl(this.rootDir, this.entrypoint);\n        return this.analyzerImpl.analyze();\n    }\n\n    /**\n     * Generate OpenAPI specification.\n     * Must be called after analyze().\n     */\n    public generateOpenAPISpec(): any {\n        if (!this.analyzerImpl) {\n            throw new Error('Must call analyze() before generateOpenAPISpec()');\n        }\n        return this.analyzerImpl.generateOpenAPISpec();\n    }\n}\n\n/**\n * Analyze a directory and generate OpenAPI spec\n */\nexport async function analyzeDirectory(directory: string): Promise<any> {\n    const analyzer = new OpenAPIAnalyzer(directory);\n    return await analyzer.analyze();\n}\n"],"names":[],"mappings":"AAYO,MAAM,gBAAgB;AAAA,EAGzB,YAAoB,SAAyB,YAAqB;AAA9C,SAAA,UAAA;AAAyB,SAAA,aAAA;AAAA,EAAuB;AAAA,EAF5D;AAAA;AAAA;AAAA;AAAA;AAAA,EAQR,MAAa,UAA6D;AAEtE,UAAM,EAAE,iBAAiB,iBAAiB,MAAM,OAAO,6BAAiB;AACxE,SAAK,eAAe,IAAI,aAAa,KAAK,SAAS,KAAK,UAAU;AAClE,WAAO,KAAK,aAAa,QAAA;AAAA,EAC7B;AAAA;AAAA;AAAA;AAAA;AAAA,EAMO,sBAA2B;AAC9B,QAAI,CAAC,KAAK,cAAc;AACpB,YAAM,IAAI,MAAM,kDAAkD;AAAA,IACtE;AACA,WAAO,KAAK,aAAa,oBAAA;AAAA,EAC7B;AACJ;"}

package/dist/analyzer-BOtveWL-.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"analyzer-BOtveWL-.cjs","sources":["../src/plugins/application/openapi/analyzer.ts"],"sourcesContent":["\n// Re-export types used in public API\nexport type { ApplicationInstance, RouteInfo } from './analyzer.impl';\nimport type { ApplicationInstance } from './analyzer.impl';\n\n/**\n * OpenAPI Analyzer Wrapper.\n * \n * This class wraps the actual OpenAPIAnalyzer implementation to facilitate\n * lazy loading of the 'typescript' peer dependency. The actual implementation\n * and the 'typescript' module are only loaded when `analyze()` is called.\n */\nexport class OpenAPIAnalyzer {\n    private analyzerImpl: any;\n\n    constructor(private rootDir: string, private entrypoint?: string) { }\n\n    /**\n     * Main analysis entry point.\n     * Dynamically imports the implementation and runs the analysis.\n     */\n    public async analyze(): Promise<{ applications: ApplicationInstance[]; }> {\n        // Dynamic import to avoid loading 'typescript' peer dependency if not needed (e.g. at runtime)\n        const { OpenAPIAnalyzer: AnalyzerImpl } = await import('./analyzer.impl');\n        this.analyzerImpl = new AnalyzerImpl(this.rootDir, this.entrypoint);\n        return this.analyzerImpl.analyze();\n    }\n\n    /**\n     * Generate OpenAPI specification.\n     * Must be called after analyze().\n     */\n    public generateOpenAPISpec(): any {\n        if (!this.analyzerImpl) {\n            throw new Error('Must call analyze() before generateOpenAPISpec()');\n        }\n        return this.analyzerImpl.generateOpenAPISpec();\n    }\n}\n\n/**\n * Analyze a directory and generate OpenAPI spec\n */\nexport async function analyzeDirectory(directory: string): Promise<any> {\n    const analyzer = new OpenAPIAnalyzer(directory);\n    return await analyzer.analyze();\n}\n"],"names":[],"mappings":";;AAYO,MAAM,gBAAgB;AAAA,EAGzB,YAAoB,SAAyB,YAAqB;AAA9C,SAAA,UAAA;AAAyB,SAAA,aAAA;AAAA,EAAuB;AAAA,EAF5D;AAAA;AAAA;AAAA;AAAA;AAAA,EAQR,MAAa,UAA6D;AAEtE,UAAM,EAAE,iBAAiB,iBAAiB,MAAM,QAAA,QAAA,EAAA,KAAA,MAAA,QAAO,8BAAiB,CAAA;AACxE,SAAK,eAAe,IAAI,aAAa,KAAK,SAAS,KAAK,UAAU;AAClE,WAAO,KAAK,aAAa,QAAA;AAAA,EAC7B;AAAA;AAAA;AAAA;AAAA;AAAA,EAMO,sBAA2B;AAC9B,QAAI,CAAC,KAAK,cAAc;AACpB,YAAM,IAAI,MAAM,kDAAkD;AAAA,IACtE;AACA,WAAO,KAAK,aAAa,oBAAA;AAAA,EAC7B;AACJ;;"}