shokupan 0.6.1 → 0.9.0

package/dist/plugins/{session.d.ts → middleware/session.d.ts}

@@ -1,43 +1,124 @@
 import { EventEmitter } from 'events';
-import { ShokupanContext } from '../context';
-import { Middleware } from '../types';
+import { ShokupanContext } from '../../context';
+import { Middleware } from '../../util/types';
 export interface SessionData {
     cookie: Cookie;
     [key: string]: any;
 }
 export interface SessionCookieOptions {
+    /**
+     * Maximum age of the session cookie in milliseconds.
+     */
     maxAge?: number;
+    /**
+     * Whether the session cookie should be signed.
+     */
     signed?: boolean;
+    /**
+     * Expiration date of the session cookie.
+     */
     expires?: Date;
+    /**
+     * Whether the session cookie should be HTTP-only.
+     */
     httpOnly?: boolean;
+    /**
+     * Path of the session cookie.
+     */
     path?: string;
+    /**
+     * Domain of the session cookie.
+     */
     domain?: string;
+    /**
+     * Whether the session cookie should be secure.
+     */
     secure?: boolean | 'auto';
+    /**
+     * SameSite attribute of the session cookie.
+     */
     sameSite?: boolean | 'lax' | 'strict' | 'none';
+    /**
+     * Priority of the session cookie.
+     */
     priority?: 'low' | 'medium' | 'high';
 }
 export interface SessionOptions {
+    /**
+     * Secret used to sign the session cookie.
+     */
     secret: string | string[];
+    /**
+     * Name of the session cookie.
+     */
     name?: string;
+    /**
+     * Store to use for session data.
+     */
     store?: Store;
+    /**
+     * Options for the session cookie.
+     */
     cookie?: SessionCookieOptions;
+    /**
+     * Function to generate a session ID.
+     */
     genid?: (ctx: ShokupanContext) => string;
+    /**
+     * Whether to force a session identifier cookie to be set on every response.
+     */
     resave?: boolean;
+    /**
+     * Whether to save the session on every request.
+     */
     saveUninitialized?: boolean;
+    /**
+     * Whether to update the session cookie on every request.
+     */
     rolling?: boolean;
+    /**
+     * Whether to destroy or keep the session on logout.
+     */
     unset?: 'destroy' | 'keep';
 }
 export interface Store extends EventEmitter {
+    /**
+     * Retrieves a session by ID.
+     */
     get(sid: string, callback: (err: any, session?: SessionData | null) => void): void;
+    /**
+     * Stores a session.
+     */
     set(sid: string, session: SessionData, callback?: (err?: any) => void): void;
+    /**
+     * Destroys a session.
+     */
     destroy(sid: string, callback?: (err?: any) => void): void;
+    /**
+     * Touches a session.
+     */
     touch?(sid: string, session: SessionData, callback?: (err?: any) => void): void;
+    /**
+     * Retrieves all sessions.
+     */
     all?(callback: (err: any, obj?: {
         [sid: string]: SessionData;
     } | null) => void): void;
+    /**
+     * Retrieves the number of sessions.
+     */
     length?(callback: (err: any, length?: number) => void): void;
+    /**
+     * Clears all sessions.
+     */
     clear?(callback?: (err?: any) => void): void;
+    /**
+     * Loads a session.
+     */
     load?(sid: string, fn: (err: any, session?: SessionData | null) => void): void;
+    /**
+     * Creates a session.
+     */
     createSession?(req: any, session: SessionData): SessionData;
 }
 declare class Cookie implements SessionCookieOptions {
@@ -76,12 +157,17 @@ export interface SessionContext {
     sessionID: string;
     sessionStore: Store;
 }
-declare module "../context" {
+declare module "../../context" {
     interface ShokupanContext {
         session: SessionContext['session'];
         sessionID: string;
         sessionStore: Store;
     }
 }
+/**
+ * Session middleware.
+ * @param options Session options
+ * @returns Middleware function
+ */
 export declare function Session(options: SessionOptions): Middleware;
 export {};

package/dist/plugins/{validation.d.ts → middleware/validation.d.ts}

@@ -1,4 +1,4 @@
-import { Middleware } from '../types';
+import { Middleware } from '../../util/types';
 export interface ValidationConfig {
     body?: any;
     query?: any;
@@ -15,4 +15,9 @@ export declare const valibot: (schema: any, parser: Function) => {
     schema: any;
     parser: Function;
 };
+/**
+ * Validation middleware.
+ * @param config Validation configuration
+ * @returns Middleware function
+ */
 export declare function validate(config: ValidationConfig): Middleware;

package/dist/router.d.ts

@@ -1,8 +1,7 @@
 import { ShokupanContext } from './context';
 import { Shokupan } from './shokupan';
-import { $appRoot, $childControllers, $childRouters, $isApplication, $isMounted, $isRouter, $mountPath, $parent, $routes } from './symbol';
-import { GuardAPISpec, JSXRenderer, Method, MethodAPISpec, Middleware, OpenAPIOptions, ProcessResult, RequestOptions, RouteMetadata, RouteParams, ShokupanController, ShokupanHandler, ShokupanHooks, ShokupanRoute, ShokupanRouteConfig, StaticServeOptions } from './types';
-type HeadersInit = Headers | Record<string, string> | [string, string][];
+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>>;
 export declare const ShokupanApplicationTree: {};
 /**
@@ -92,6 +91,9 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
         autoBackpressureLevel?: number;
         enableMiddlewareTracking?: boolean;
         middlewareTrackingMaxCapacity?: number;
+        enableHTTPBridge?: boolean;
+        websocketErrorHandler?: (err: any, ctx: ShokupanContext<Record<string, any>, Record<string, string>>) => void | Promise<void>;
+        idGenerator?: () => string;
         middlewareTrackingTTL?: number;
         httpLogger?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>) => void;
         logger?: {
@@ -106,7 +108,7 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
         requestTimeout?: number;
         writeTimeout?: number;
         renderer?: JSXRenderer;
-        serverFactory?: import('./types').ServerFactory;
+        serverFactory?: import('.').ServerFactory;
         hooks?: {
             onError?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>, error: unknown) => void | Promise<void>;
             onRequestStart?: (ctx: ShokupanContext<Record<string, any>, Record<string, string>>) => void | Promise<void>;
@@ -137,6 +139,7 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
     private trie;
     metadata?: RouteMetadata;
     private currentGuards;
+    private eventHandlers;
     getComponentRegistry(): {
         metadata: RouteMetadata;
         middleware: {
@@ -175,6 +178,14 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
     };
     constructor(config?: ShokupanRouteConfig);
     private isRouterInstance;
+    /**
+     * Registers an event handler for WebSocket.
+     */
+    event(name: string, handler: ShokupanHandler<T>): this;
+    /**
+     * Finds an event handler(s) by name.
+     */
+    findEvent(name: string): ShokupanHandler<T>[] | null;
     /**
      * Mounts a controller instance to a path prefix.
      *
@@ -212,6 +223,8 @@ 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
@@ -388,4 +401,3 @@ export declare class ShokupanRouter<T extends Record<string, any> = Record<strin
     private ensureHooksInitialized;
     runHooks(name: keyof ShokupanHooks, ...args: any[]): Promise<void>;
 }
-export {};

package/dist/shokupan.d.ts

@@ -1,8 +1,8 @@
-import { ShokupanRequest } from './request';
-import { ShokupanRouter } from './router';
-import { $dispatch } from './symbol';
-import { Middleware, ProcessResult, RequestOptions, ShokupanConfig } from './types';
+import { $dispatch } from './util/symbol';
+import { Middleware, ProcessResult, RequestOptions, ShokupanConfig, ShokupanPlugin } from './util/types';
 import { Server } from 'bun';
+import { ShokupanRouter } from './router';
+import { ShokupanRequest } from './util/request';
 /**
  * Shokupan Application
  *
@@ -72,6 +72,7 @@ export declare class Shokupan<T = any> extends ShokupanRouter<T> {
     openApiSpec?: any;
     private composedMiddleware?;
     private cpuMonitor?;
+    private server?;
     get logger(): {
         verbose?: boolean;
         info?: (msg: string, props: Record<string, any>) => void;
@@ -85,6 +86,12 @@ export declare class Shokupan<T = any> extends ShokupanRouter<T> {
      * Adds middleware to the application.
      */
     use(middleware: Middleware): this;
+    /**
+     * Registers a plugin.
+     */
+    register(plugin: ShokupanPlugin, options?: {
+        path?: string;
+    }): this;
     private startupHooks;
     /**
      * Registers a callback to be executed before the server starts listening.
@@ -102,7 +109,26 @@ export declare class Shokupan<T = any> extends ShokupanRouter<T> {
      * @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.
      */
-    listen(port?: number): Promise<Server | import('http').Server<typeof import('http').IncomingMessage, typeof import('http').ServerResponse>>;
+    listen(port?: number): Promise<Server>;
+    /**
+     * Stops the application server.
+     *
+     * This method gracefully shuts down the server and stops any running monitors.
+     * Works transparently in both Bun and Node.js runtimes.
+     *
+     * @returns A promise that resolves when the server has been stopped.
+     *
+     * @example
+     * ```typescript
+     * const app = new Shokupan();
+     * const server = await app.listen(3000);
+     *
+     * // Later, when you want to stop the server
+     * await app.stop();
+     * ```
+     * @param closeActiveConnections — Immediately terminate in-flight requests, websockets, and stop accepting new connections.
+     */
+    stop(closeActiveConnections?: boolean): Promise<void>;
     [$dispatch](req: ShokupanRequest<T>): Promise<Response>;
     /**
      * Processes a request by wrapping the standard fetch method.

package/dist/util/async-hooks.d.ts

@@ -1,3 +1,9 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
-export declare const asyncContext: AsyncLocalStorage<Map<string, any>>;
-export declare function runInContext<T>(callback: () => T, initialStore?: Map<string, any>): T;
+import { Span } from '@opentelemetry/api';
+export declare class RequestContextStore {
+    request?: Request;
+    span?: Span;
+    [key: string]: any;
+}
+export declare const asyncContext: AsyncLocalStorage<RequestContextStore>;
+export declare function runInContext<T>(callback: () => T, initialStore?: RequestContextStore): T;

package/dist/util/datastore.d.ts

@@ -1,6 +1,7 @@
+import { RecordId, Range, Table } from 'surrealdb';
 export declare const datastore: {
-    get<T extends Record<string, any>>(store: string, key: string): Promise<T>;
-    set(store: string, key: string, value: any): Promise<any>;
-    query(query: string, vars?: Record<string, unknown>): Promise<any>;
+    get<T extends Record<string, any>>(recordId: RecordId | Table | Range<any, any>): Promise<T>;
+    set(recordId: RecordId, value: Record<string, any>): Promise<any>;
+    query<T extends Record<string, any>>(query: string, vars?: Record<string, unknown>): Promise<T>;
     readonly ready: Promise<any>;
 };

package/dist/{decorators.d.ts → util/decorators.d.ts}

@@ -1,4 +1,4 @@
-import { RateLimitOptions } from './plugins/rate-limit';
+import { RateLimitOptions } from '../plugins/middleware/rate-limit';
 import { GuardAPISpec, MethodAPISpec, Middleware } from './types';
 /**
  * Class Decorator: Defines the base path for a controller.
@@ -68,6 +68,11 @@ export declare const Head: (path?: string) => (target: any, propertyKey: string,
  * Decorator: Binds a method to ANY HTTP verb.
  */
 export declare const All: (path?: string) => (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+/**
+ * Decorator: Binds a method to the WebSocket event.
+ * @param eventName The name of the event to listen for.
+ */
+export declare function Event(eventName: string): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
 /**
  * Decorator: Applies a rate limit to a class or method.
  */

package/dist/util/http-error.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Standard HTTP Error class with status code.
+ * This standardizes on the `status` property instead of dual `status`/`statusCode`.
+ */
+export declare class HttpError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+/**
+ * Extracts HTTP status code from an error object.
+ * Supports both `status` and `statusCode` properties for backward compatibility.
+ * Defaults to 500 (Internal Server Error) if no status is found.
+ *
+ * @param err - Error object (may have `status` or `statusCode` property)
+ * @returns HTTP status code
+ */
+export declare function getErrorStatus(err: any): number;
+/**
+ * Common HTTP Errors
+ */
+export declare class BadRequestError extends HttpError {
+    constructor(message?: string);
+}
+export declare class UnauthorizedError extends HttpError {
+    constructor(message?: string);
+}
+export declare class ForbiddenError extends HttpError {
+    constructor(message?: string);
+}
+export declare class NotFoundError extends HttpError {
+    constructor(message?: string);
+}
+export declare class InternalServerError extends HttpError {
+    constructor(message?: string);
+}
+export declare class EventError extends HttpError {
+    constructor(message?: string);
+}

package/dist/util/http-status.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Common HTTP Status Codes
+ * Use these constants instead of magic numbers for better readability
+ */
+export declare const HTTP_STATUS: {
+    readonly OK: 200;
+    readonly CREATED: 201;
+    readonly ACCEPTED: 202;
+    readonly NO_CONTENT: 204;
+    readonly MOVED_PERMANENTLY: 301;
+    readonly FOUND: 302;
+    readonly SEE_OTHER: 303;
+    readonly NOT_MODIFIED: 304;
+    readonly TEMPORARY_REDIRECT: 307;
+    readonly PERMANENT_REDIRECT: 308;
+    readonly BAD_REQUEST: 400;
+    readonly UNAUTHORIZED: 401;
+    readonly FORBIDDEN: 403;
+    readonly NOT_FOUND: 404;
+    readonly METHOD_NOT_ALLOWED: 405;
+    readonly REQUEST_TIMEOUT: 408;
+    readonly CONFLICT: 409;
+    readonly UNPROCESSABLE_ENTITY: 422;
+    readonly TOO_MANY_REQUESTS: 429;
+    readonly INTERNAL_SERVER_ERROR: 500;
+    readonly NOT_IMPLEMENTED: 501;
+    readonly BAD_GATEWAY: 502;
+    readonly SERVICE_UNAVAILABLE: 503;
+    readonly GATEWAY_TIMEOUT: 504;
+};
+export declare const VALID_HTTP_STATUSES: Set<number>;
+export declare const VALID_REDIRECT_STATUSES: Set<number>;

package/dist/util/instrumentation.d.ts

@@ -1,4 +1,4 @@
-import { Middleware, ShokupanHandler } from '../types';
+import { Middleware, ShokupanHandler } from './types';
 /**
  * Wraps a middleware function with an OpenTelemetry span.
  */

package/dist/{request.d.ts → util/request.d.ts}

@@ -2,7 +2,7 @@ import { Method } from './types';
 export type ShokupanRequestProps = {
     method: Method;
     url: string;
-    headers: Headers;
+    headers: Headers | Record<string, string>;
     body: any;
 };
 /**

package/dist/util/symbol.d.ts

@@ -0,0 +1,34 @@
+export declare const $isApplication: unique symbol;
+export declare const $appRoot: unique symbol;
+export declare const $isMounted: unique symbol;
+export declare const $routeMethods: unique symbol;
+export declare const $eventMethods: unique symbol;
+export declare const $routeArgs: unique symbol;
+export declare const $controllerPath: unique symbol;
+export declare const $middleware: unique symbol;
+export declare const $isRouter: unique symbol;
+export declare const $parent: unique symbol;
+export declare const $childRouters: unique symbol;
+export declare const $childControllers: unique symbol;
+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 $url: unique symbol;
+export declare const $requestId: unique symbol;
+export declare const $debug: unique symbol;
+export declare const $finalResponse: unique symbol;
+export declare const $rawBody: unique symbol;
+export declare const $cachedBody: unique symbol;
+export declare const $bodyType: unique symbol;
+export declare const $bodyParsed: unique symbol;
+export declare const $bodyParseError: unique symbol;
+export declare const $routeMatched: unique symbol;
+export declare const $cachedHostname: unique symbol;
+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 $ws: unique symbol;
+export declare const $socket: unique symbol;
+export declare const $io: unique symbol;

package/dist/{router → util}/trie.d.ts

@@ -1,4 +1,4 @@
-import { Method, ShokupanHandler } from '../types';
+import { Method, ShokupanHandler } from './types';
 export interface RouteMatch<T = any> {
     handler: ShokupanHandler<T>;
     params: Record<string, string>;

package/dist/{types.d.ts → util/types.d.ts}

@@ -1,8 +1,15 @@
 import { OpenAPI } from '@scalar/openapi-types';
 import { Server } from 'bun';
 import { Server as NodeServer } from 'node:http';
-import { ShokupanContext } from './context';
+import { ShokupanContext } from '../context';
 import { $isRouter } from './symbol';
+export type HeadersInit = Headers | Record<string, string> | [string, string][];
+export interface ShokupanPluginOptions {
+    path?: string;
+}
+export interface ShokupanPlugin {
+    onInit: (app: any, options?: ShokupanPluginOptions) => void | Promise<void>;
+}
 export type DeepPartial<T> = T extends Function ? T : T extends object ? {
     [P in keyof T]?: DeepPartial<T[P]>;
 } : T;
@@ -76,7 +83,9 @@ export interface CookieOptions {
     sameSite?: boolean | 'lax' | 'strict' | 'none' | 'Lax' | 'Strict' | 'None';
     priority?: 'low' | 'medium' | 'high' | 'Low' | 'Medium' | 'High';
 }
-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;
+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>;
+};
 export declare const HTTPMethods: string[];
 export type Method = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "OPTIONS" | "HEAD" | "ALL";
 export declare enum RouteParamType {
@@ -282,6 +291,33 @@ export type ShokupanConfig<T extends Record<string, any> = Record<string, any>>
      * @default 10000
      */
     middlewareTrackingMaxCapacity?: number;
+    /**
+     * Whether to enable the HTTP bridge for WebSocket.
+     * This enables websocket messages to run through the HTTP server.
+     * e.g.
+     * ```json
+     * {
+     *  "method": "POST",
+     *  "path": "/api/v1/myHttpEndpoint",
+     *  "headers": {},
+     *  "body": {
+     *      "type": "text",
+     *      "data": "Hello, world!"
+     *  }
+     * }
+     * ```
+     * @default false
+     */
+    enableHTTPBridge?: boolean;
+    /**
+     * Handler for WebSocket events that throw an exception.
+     */
+    websocketErrorHandler?: (err: any, ctx: ShokupanContext<T>) => void | Promise<void>;
+    /**
+     * Unique ID generator function for requests.
+     * @default nanoid
+     */
+    idGenerator?: () => string;
     /**
      * Time-to-live for middleware tracking entries in milliseconds.
      * Entries older than this will be cleaned up.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "shokupan",
-    "version": "0.6.1",
+    "version": "0.9.0",
     "description": "Shokupan is a low-lift modern web framework for Bun.",
     "author": "Andrew G. Knackstedt",
     "publishConfig": {
@@ -22,12 +22,12 @@
     ],
     "type": "module",
     "scripts": {
-        "dev": "bun --watch --inspect src/example/main.ts",
+        "dev": "bun --watch --inspect examples/full/main.ts",
         "debug:otel": "sh scripts/debug-otel.sh",
         "docs": "cd docs && bun run dev",
         "build": "vite build",
-        "bench": "cd src/benchmarking && bun runner.ts",
-        "bench:advanced": "cd src/benchmarking && bun advanced-runner.ts",
+        "bench": "cd benchmarking && bun runner.ts",
+        "bench:advanced": "cd benchmarking && bun advanced-runner.ts",
         "retag": "git push origin :refs/tags/v$(node -p \"require('./package.json').version\") 2>/dev/null || true && git tag -d v$(node -p \"require('./package.json').version\") 2>/dev/null || true && git tag v$(node -p \"require('./package.json').version\") && git push origin v$(node -p \"require('./package.json').version\") --force"
     },
     "bin": {
@@ -65,9 +65,13 @@
         "@opentelemetry/sdk-trace-node": "^2.2.0",
         "@opentelemetry/semantic-conventions": "^1.38.0",
         "@scalar/openapi-types": "^0.5.3",
+        "nanoid": "^5.1.6",
+        "socket.io": "^4.8.3",
         "tslib": "^2.8.1"
     },
     "peerDependencies": {
+        "@scalar/api-reference": "^1.0.0",
+        "@surrealdb/node": "^2.4.0",
         "ajv": "^8.0.0",
         "ajv-formats": "^3.0.0",
         "arctic": "^3",
@@ -78,8 +82,6 @@
         "parse-json": "^8.0.0",
         "reflect-metadata": "^0.2.0",
         "secure-json-parse": "^4.0.0",
-        "@scalar/api-reference": "^1.0.0",
-        "@surrealdb/node": "^2.4.0",
         "surrealdb": "^2.0.0-alpha.14"
     },
     "peerDependenciesMeta": {
@@ -150,6 +152,7 @@
         "valibot": "^1.2.0",
         "vite": "^7.3.0",
         "vite-plugin-dts": "^4.5.4",
+        "vite-plugin-static-copy": "^3.1.4",
         "zod": "^4.2.1"
     }
 }