shokupan 0.10.4 → 0.11.0

package/dist/router.d.ts

@@ -74,6 +74,27 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
     private [$parent];
     [$childRouters]: ShokupanRouter<T>[];
     [$childControllers]: ShokupanController[];
+    private _hasOnResponseEndHook;
+    private _hasOnRequestStartHook;
+    private _hasOnRequestEndHook;
+    private _hasOnResponseStartHook;
+    private _hasOnErrorHook;
+    private _hasOnRequestTimeoutHook;
+    private _hasOnReadTimeoutHook;
+    private _hasOnWriteTimeoutHook;
+    private _hasBeforeValidateHook;
+    private _hasAfterValidateHook;
+    get hasOnResponseEndHook(): boolean;
+    get hasOnRequestStartHook(): boolean;
+    get hasOnRequestEndHook(): boolean;
+    get hasOnResponseStartHook(): boolean;
+    get hasOnErrorHook(): boolean;
+    get hasOnRequestTimeoutHook(): boolean;
+    get hasOnReadTimeoutHook(): boolean;
+    get hasOnWriteTimeoutHook(): boolean;
+    get hasBeforeValidateHook(): boolean;
+    get hasAfterValidateHook(): boolean;
+    requestTimeout?: number;
     get db(): SurrealDatastore | undefined;
     private hookCache;
     private hooksInitialized;
@@ -85,7 +106,9 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
         development: boolean;
         enableAsyncLocalStorage: boolean;
         enableOpenApiGen: boolean;
+        blockOnOpenApiGen: boolean;
         enableAsyncApiGen: boolean;
+        blockOnAsyncApiGen: boolean;
         reusePort: boolean;
         controllersOnly: boolean;
         enableTracing?: boolean;
@@ -112,6 +135,8 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
         writeTimeout: number;
         renderer: JSXRenderer;
         serverFactory: import('.').ServerFactory;
+        adapter?: "bun" | "node" | "wintercg" | import('./util/adapter/adapters').ServerAdapter;
+        fileSystem?: import('./util/adapter/filesystem').FileSystemAdapter;
         hooks: ShokupanHooks<Record<string, any>> | ShokupanHooks<Record<string, any>>[];
         validateStatusCodes: boolean;
         surreal?: {
@@ -195,6 +220,13 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
                 routes: any[];
             };
         }[];
+        events: {
+            type: 'event';
+            name: string;
+            handlerName: string;
+            metadata: RouteMetadata;
+            _fn: ShokupanHandler<T>;
+        }[];
     };
     constructor(config?: ShokupanRouteConfig);
     private isRouterInstance;
@@ -202,10 +234,18 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
      * Registers an event handler for WebSocket.
      */
     event(name: string, handler: ShokupanHandler<T>): this;
+    /**
+     * Registers a lifecycle hook dynamically.
+     */
+    hook(name: keyof ShokupanHooks, handler: Function): this;
     /**
      * Finds an event handler(s) by name.
      */
     findEvent(name: string): ShokupanHandler<T>[] | null;
+    /**
+     * Registers a controller instance to the router.
+     */
+    registerControllerInstance(controller: any): void;
     /**
      * Returns all registered event handlers.
      */
@@ -248,7 +288,6 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
     testRequest(options: RequestOptions): Promise<ProcessResult>;
     private wrapWithHooks;
     private mountRouter;
-    private scanControllerRoutes;
     /**
      * Find a route matching the given method and path.
      * @param method HTTP method
@@ -260,7 +299,6 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
         params: Record<string, string>;
     } | null;
     private parsePath;
-    requestTimeout?: number;
     /**
      * Adds a route to the router.
      *
@@ -297,7 +335,7 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
      * @param path - URL path
      * @param handlers - Route handler functions
      */
-    get<Path extends string>(path: Path, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
+    get<Path extends string>(path: Path, handler: ShokupanHandler<T, RouteParams<Path>>, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
     /**
      * Adds a GET route to the router.
      *
@@ -305,14 +343,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 extends string>(path: Path, spec: MethodAPISpec, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
+    get<Path extends string>(path: Path, spec: MethodAPISpec, handler: ShokupanHandler<T, RouteParams<Path>>, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
     /**
      * Adds a POST route to the router.
      *
      * @param path - URL path
      * @param handlers - Route handler functions
      */
-    post<Path extends string>(path: Path, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
+    post<Path extends string>(path: Path, handler: ShokupanHandler<T, RouteParams<Path>>, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
     /**
      * Adds a POST route to the router.
      *
@@ -320,14 +358,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 extends string>(path: Path, spec: MethodAPISpec, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
+    post<Path extends string>(path: Path, spec: MethodAPISpec, handler: ShokupanHandler<T, RouteParams<Path>>, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
     /**
      * Adds a PUT route to the router.
      *
      * @param path - URL path
      * @param handlers - Route handler functions
      */
-    put<Path extends string>(path: Path, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
+    put<Path extends string>(path: Path, handler: ShokupanHandler<T, RouteParams<Path>>, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
     /**
      * Adds a PUT route to the router.
      *
@@ -335,14 +373,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 extends string>(path: Path, spec: MethodAPISpec, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
+    put<Path extends string>(path: Path, spec: MethodAPISpec, handler: ShokupanHandler<T, RouteParams<Path>>, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
     /**
      * Adds a DELETE route to the router.
      *
      * @param path - URL path
      * @param handlers - Route handler functions
      */
-    delete<Path extends string>(path: Path, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
+    delete<Path extends string>(path: Path, handler: ShokupanHandler<T, RouteParams<Path>>, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
     /**
      * Adds a DELETE route to the router.
      *
@@ -350,14 +388,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 extends string>(path: Path, spec: MethodAPISpec, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
+    delete<Path extends string>(path: Path, spec: MethodAPISpec, handler: ShokupanHandler<T, RouteParams<Path>>, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
     /**
      * Adds a PATCH route to the router.
      *
      * @param path - URL path
      * @param handlers - Route handler functions
      */
-    patch<Path extends string>(path: Path, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
+    patch<Path extends string>(path: Path, handler: ShokupanHandler<T, RouteParams<Path>>, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
     /**
      * Adds a PATCH route to the router.
      *
@@ -365,14 +403,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 extends string>(path: Path, spec: MethodAPISpec, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
+    patch<Path extends string>(path: Path, spec: MethodAPISpec, handler: ShokupanHandler<T, RouteParams<Path>>, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
     /**
      * Adds a OPTIONS route to the router.
      *
      * @param path - URL path
      * @param handlers - Route handler functions
      */
-    options<Path extends string>(path: Path, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
+    options<Path extends string>(path: Path, handler: ShokupanHandler<T, RouteParams<Path>>, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
     /**
      * Adds a OPTIONS route to the router.
      *
@@ -380,14 +418,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 extends string>(path: Path, spec: MethodAPISpec, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
+    options<Path extends string>(path: Path, spec: MethodAPISpec, handler: ShokupanHandler<T, RouteParams<Path>>, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
     /**
      * Adds a HEAD route to the router.
      *
      * @param path - URL path
      * @param handlers - Route handler functions
      */
-    head<Path extends string>(path: Path, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
+    head<Path extends string>(path: Path, handler: ShokupanHandler<T, RouteParams<Path>>, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
     /**
      * Adds a HEAD route to the router.
      *
@@ -395,7 +433,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 extends string>(path: Path, spec: MethodAPISpec, ...handlers: ShokupanHandler<T, RouteParams<Path>>[]): any;
+    head<Path extends string>(path: Path, spec: MethodAPISpec, handler: ShokupanHandler<T, RouteParams<Path>>, ...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.
@@ -427,6 +465,7 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
      * Now includes runtime analysis of handler functions to infer request/response types.
      */
     generateApiSpec(options?: OpenAPIOptions): Promise<any>;
+    hasHooks(name: keyof ShokupanHooks): boolean;
     private ensureHooksInitialized;
     runHooks(name: keyof ShokupanHooks, ...args: any[]): void | Promise<void[]>;
 }

package/dist/shokupan.d.ts

@@ -1,9 +1,9 @@
-import { $dispatch } from './util/symbol';
-import { Middleware, ProcessResult, RequestOptions, ShokupanConfig, ShokupanPlugin } from './util/types';
 import { Server } from 'bun';
 import { ShokupanRouter } from './router';
 import { SurrealDatastore } from './util/datastore';
 import { ShokupanRequest } from './util/request';
+import { $dispatch } from './util/symbol';
+import { Middleware, ProcessResult, RequestOptions, ShokupanConfig, ShokupanPlugin } from './util/types';
 /**
  * Shokupan Application
  *
@@ -72,6 +72,8 @@ export declare class Shokupan<T = any> extends ShokupanRouter<T> {
     readonly applicationConfig: ShokupanConfig;
     openApiSpec?: any;
     asyncApiSpec?: any;
+    private openApiSpecPromise?;
+    private asyncApiSpecPromise?;
     private composedMiddleware?;
     private cpuMonitor?;
     private server?;
@@ -88,6 +90,9 @@ export declare class Shokupan<T = any> extends ShokupanRouter<T> {
     };
     constructor(applicationConfig?: ShokupanConfig);
     private initDatastore;
+    /**
+     * Adds middleware to the application.
+     */
     /**
      * Adds middleware to the application.
      */

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

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

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

@@ -0,0 +1,20 @@
+export interface FileSystemAdapter {
+    readFile(path: string): Promise<Uint8Array | string | ReadableStream>;
+    stat?(path: string): Promise<{
+        size: number;
+        mtime: Date;
+    }>;
+}
+/**
+ * Default file system adapter that uses Bun.file for Bun and Node.js fs.promises for Node.js.
+ */
+export declare class DefaultFileSystemAdapter implements FileSystemAdapter {
+    readFile(path: string): Promise<Uint8Array | string | ReadableStream>;
+    stat(path: string): Promise<{
+        size: number;
+        mtime: Date;
+    }>;
+}
+export declare class NoOpFileSystemAdapter implements FileSystemAdapter {
+    readFile(path: string): Promise<Uint8Array | string | ReadableStream>;
+}

package/dist/util/controller-scanner.d.ts

@@ -0,0 +1,4 @@
+import { ShokupanRouter } from '../router';
+export declare class ControllerScanner {
+    static scan<T extends Record<string, any>>(router: ShokupanRouter<T>, prefix: string, controller: any): void;
+}

package/dist/util/cpu-monitor.d.ts

@@ -3,7 +3,9 @@ export declare class SystemCpuMonitor {
     private interval;
     private lastCpus;
     private currentUsage;
+    private osStub;
     constructor(intervalMs?: number);
+    private init;
     start(): void;
     stop(): void;
     getUsage(): number;

package/dist/util/middleware-tracker.d.ts

@@ -0,0 +1,10 @@
+import { Middleware, ShokupanHandler } from '../util/types';
+export declare class MiddlewareTracker {
+    static wrap(handler: Middleware | ShokupanHandler<any>, context: {
+        file: string;
+        line: number;
+        name?: string;
+        isBuiltin?: boolean;
+        pluginName?: string;
+    }): any;
+}

package/dist/util/types.d.ts

@@ -61,6 +61,15 @@ export interface OpenAPIOptions {
     externalDocs?: OpenAPI.Document['externalDocs'];
     defaultTagGroup?: string;
     defaultTag?: string;
+    /**
+     * Whether to generate a strictly compliant OpenAPI spec (stripping x- extensions).
+     * @default false
+     */
+    compliant?: boolean;
+    /**
+     * Array to collect warnings during generation.
+     */
+    warnings?: any[];
 }
 export interface AsyncAPIOptions {
     info?: {
@@ -69,6 +78,10 @@ export interface AsyncAPIOptions {
         description?: string;
     };
     defaultTag?: string;
+    /**
+     * Array to collect warnings during generation.
+     */
+    warnings?: any[];
 }
 export interface AsyncAPISpec {
     type?: 'publish' | 'subscribe';
@@ -263,11 +276,25 @@ export type ShokupanConfig<T extends Record<string, any> = Record<string, any>>
      * @default true
      */
     enableOpenApiGen: boolean;
+    /**
+     * Whether to block server startup until OpenAPI generation completes.
+     * Only applies when enableOpenApiGen is true.
+     * When false, OpenAPI generation happens asynchronously in the background.
+     * @default true
+     */
+    blockOnOpenApiGen: boolean;
     /**
      * Whether to enable AsyncAPI generation.
      * @default false
      */
     enableAsyncApiGen: boolean;
+    /**
+     * Whether to block server startup until AsyncAPI generation completes.
+     * Only applies when enableAsyncApiGen is true.
+     * When false, AsyncAPI generation happens asynchronously in the background.
+     * @default true
+     */
+    blockOnAsyncApiGen: boolean;
     /**
      * Whether to reuse the port.
      * @default false
@@ -399,8 +426,18 @@ export type ShokupanConfig<T extends Record<string, any> = Record<string, any>>
     /**
      * Factory function to create the server instance.
      * Defaults to Bun.serve.
+     * @deprecated Use `adapter` instead.
      */
     serverFactory: ServerFactory;
+    /**
+     * The server adapter to use.
+     * overrides `serverFactory`.
+     */
+    adapter?: 'bun' | 'node' | 'wintercg' | import('./adapter/adapters').ServerAdapter;
+    /**
+     * The file system adapter to use for `ctx.file`.
+     */
+    fileSystem?: import('./adapter/filesystem').FileSystemAdapter;
     /**
      * Lifecycle hooks.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "shokupan",
-    "version": "0.10.4",
+    "version": "0.11.0",
     "description": "Shokupan is a low-lift modern web framework for Bun.",
     "author": "Andrew G. Knackstedt",
     "publishConfig": {
@@ -71,6 +71,7 @@
         "tslib": "^2.8.1"
     },
     "peerDependencies": {
+        "@apollo/server": "^5.2.0",
         "@scalar/api-reference": "^1.0.0",
         "@surrealdb/node": "^2.4.0",
         "ajv": "^8.0.0",
@@ -79,14 +80,13 @@
         "class-transformer": "^0.5.0",
         "class-validator": "^0.14.0",
         "eta": "^4.0.0",
+        "graphql": "^16.12.0",
+        "graphql-yoga": "^5.18.0",
         "jose": "^6.0.0",
         "parse-json": "^8.0.0",
         "reflect-metadata": "^0.2.0",
         "secure-json-parse": "^4.0.0",
-        "surrealdb": "^2.0.0-alpha.16",
-        "@apollo/server": "^5.2.0",
-        "graphql-yoga": "^5.18.0",
-        "graphql": "^16.12.0"
+        "surrealdb": "^2.0.0-alpha.16"
     },
     "peerDependenciesMeta": {
         "ajv": {