shokupan 0.6.0 → 0.7.0

package/dist/middleware.d.ts

@@ -1,5 +1,5 @@
 import { ShokupanContext } from './context';
-import { Middleware, NextFn } from './types';
+import { Middleware, NextFn } from './util/types';
 /**
  * Composes a list of middleware into a single function.
  * This is the onion model (Koa-style).

package/dist/plugins/{auth.d.ts → application/auth.d.ts}

@@ -1,5 +1,7 @@
-import { ShokupanContext } from '../context';
-import { ShokupanRouter } from '../router';
+import { ShokupanContext } from '../../context';
+import { ShokupanRouter } from '../../router';
+import { Shokupan } from '../../shokupan';
+import { ShokupanPlugin, ShokupanPluginOptions } from '../../util/types';
 export interface AuthUser {
     id: string;
     email?: string;
@@ -9,29 +11,92 @@ export interface AuthUser {
     raw?: any;
 }
 export interface ProviderConfig {
+    /**
+     * Client ID
+     */
     clientId: string;
+    /**
+     * Client secret
+     */
     clientSecret: string;
+    /**
+     * Redirect URI
+     */
     redirectUri: string;
+    /**
+     * Scopes
+     */
     scopes?: string[];
+    /**
+     * Tenant ID (MSFT AD)
+     */
     tenantId?: string;
+    /**
+     * Domain (Auth0, Okta)
+     */
     domain?: string;
+    /**
+     * Team ID (Apple)
+     */
     teamId?: string;
+    /**
+     * Key ID (Apple)
+     */
     keyId?: string;
+    /**
+     * Auth URL (Generic OAuth2)
+     */
     authUrl?: string;
+    /**
+     * Token URL (Generic OAuth2)
+     */
     tokenUrl?: string;
+    /**
+     * User info URL (Generic OAuth2)
+     */
     userInfoUrl?: string;
 }
 export interface AuthConfig {
+    /**
+     * JWT secret
+     */
     jwtSecret: string | Uint8Array;
+    /**
+     * JWT expiration
+     */
     jwtExpiration?: string;
+    /**
+     * Cookie options
+     */
     cookieOptions?: {
+        /**
+         * HTTP only
+         */
         httpOnly?: boolean;
+        /**
+         * Secure
+         */
         secure?: boolean;
+        /**
+         * Same site
+         */
         sameSite?: "Strict" | "Lax" | "None";
+        /**
+         * Path
+         */
         path?: string;
+        /**
+         * Max age
+         */
         maxAge?: number;
     };
+    /**
+     * Success callback
+     */
     onSuccess?: (user: AuthUser, ctx: ShokupanContext) => Promise<any> | any;
+    /**
+     * Providers
+     */
     providers: {
         github?: ProviderConfig;
         google?: ProviderConfig;
@@ -43,10 +108,14 @@ export interface AuthConfig {
         [key: string]: ProviderConfig | undefined;
     };
 }
-export declare class AuthPlugin extends ShokupanRouter<any> {
+/**
+ * Authentication plugin
+ */
+export declare class AuthPlugin extends ShokupanRouter<any> implements ShokupanPlugin {
     private authConfig;
     private secret;
     constructor(authConfig: AuthConfig);
+    onInit(app: Shokupan, options?: ShokupanPluginOptions): void;
     private getProviderInstance;
     private createSession;
     private init;

package/dist/plugins/application/cluster.d.ts

@@ -0,0 +1,33 @@
+import { Shokupan } from '../../shokupan';
+import { ShokupanPlugin } from '../../util/types';
+export interface ClusterOptions {
+    /**
+     * Number of workers to spawn.
+     * Set to -1 or 'auto' to spawn one worker per available CPU.
+     * @default 'auto'
+     */
+    workers?: number | 'auto';
+    /**
+     * Whether to pipe stdout/stderr to the parent process.
+     * @default false
+     */
+    silent?: boolean;
+    /**
+     * Enable sticky sessions (useful for Socket.io).
+     * Currently only supported in Node.js runtime.
+     * @default false
+     */
+    sticky?: boolean;
+}
+/**
+ * Cluster Plugin
+ *
+ * Automatically manages clustering for Node.js and Bun.
+ */
+export declare class ClusterPlugin implements ShokupanPlugin {
+    private options;
+    constructor(options?: ClusterOptions);
+    onInit(app: Shokupan): void;
+    private handleBun;
+    private handleNode;
+}

package/dist/plugins/{failed-request-recorder.d.ts → application/dashboard/failed-request-recorder.d.ts}

@@ -1,4 +1,4 @@
-import { Middleware } from '../types';
+import { Middleware } from '../../../util/types';
 export interface FailedRequestRecorderOptions {
     /**
      * Maximum number of failed requests to keep.

package/dist/plugins/{debugview → application/dashboard}/plugin.d.ts

@@ -1,5 +1,6 @@
-import { ShokupanRouter } from '../../router';
-import { ShokupanHooks } from '../../types';
+import { ShokupanContext } from '../../../context';
+import { ShokupanRouter } from '../../../router';
+import { ShokupanHooks } from '../../../util/types';
 export interface RequestLog {
     method: string;
     url: string;
@@ -8,17 +9,23 @@ export interface RequestLog {
     timestamp: number;
     handlerStack?: any[];
 }
-export interface DebugDashboardConfig {
-    getRequestHeaders?: () => Record<string, string>;
+export interface DashboardConfig {
+    /**
+     * Function to get request headers to include in the debug dashboard
+     */
+    getHeaders?: (ctx: ShokupanContext) => Record<string, string>;
+    /**
+     * Retention time in milliseconds
+     */
     retentionMs?: number;
 }
-export declare class DebugDashboard extends ShokupanRouter {
+export declare class Dashboard extends ShokupanRouter {
     private readonly dashboardConfig;
     private metrics;
     private eta;
     private startTime;
     private instrumented;
-    constructor(dashboardConfig?: DebugDashboardConfig);
+    constructor(dashboardConfig?: DashboardConfig);
     private instrumentApp;
     private assignIdsToRegistry;
     recordNodeMetric(id: string, type: string, duration: number, isError: boolean): void;

package/dist/plugins/{server-adapter.d.ts → application/http-server.d.ts}

@@ -1,4 +1,4 @@
-import { ServerFactory } from '../types';
+import { ServerFactory } from '../../util/types';
 import * as https from "node:https";
 /**
  * Creates a server factory that uses the standard Node.js `http` module.

package/dist/plugins/{idempotency → application/idempotency}/plugin.d.ts

@@ -1,4 +1,4 @@
-import { Middleware } from '../../types';
+import { Middleware } from '../../../util/types';
 export interface IdempotencyOptions {
     /**
      * Header name to use for the idempotency key.
@@ -11,4 +11,10 @@ export interface IdempotencyOptions {
      */
     ttl?: number;
 }
+/**
+ * Idempotency middleware. This middleware will cache responses based on the idempotency key
+ * to prevent duplicate server processing of requests.
+ * @param options Idempotency options
+ * @returns Middleware
+ */
 export declare function Idempotency(options?: IdempotencyOptions): Middleware;

package/dist/plugins/{openapi.d.ts → application/openapi/openapi.d.ts}

@@ -1,5 +1,5 @@
-import { ShokupanRouter } from '../router';
-import { OpenAPIOptions } from '../types';
+import { ShokupanRouter } from '../../../router';
+import { OpenAPIOptions } from '../../../util/types';
 /**
  * Statically generate an OpenAPI spec from a ShokupanRouter instance.
  *

package/dist/plugins/application/scalar.d.ts

@@ -0,0 +1,36 @@
+import { ApiReferenceConfiguration } from '@scalar/api-reference';
+import { OpenAPI } from '@scalar/openapi-types';
+import { ShokupanRouter } from '../../router';
+import { Shokupan } from '../../shokupan';
+import { DeepPartial, ShokupanPlugin, ShokupanPluginOptions } from '../../util/types';
+export type ScalarPluginOptions = {
+    /**
+     * Base document to use for API reference.
+     */
+    baseDocument?: DeepPartial<OpenAPI.Document>;
+    /**
+     * Configuration for API reference.
+     */
+    config?: Partial<ApiReferenceConfiguration>;
+    /**
+     * Whether to enable static analysis.
+     * When this is enabled, the plugin will run static analysis on the entrypoint
+     * and generate an OpenAPI document. This is useful for when you want to generate
+     * an OpenAPI document without having to manually define it.
+     *
+     * Only works with TypeScript entrypoints.
+     */
+    enableStaticAnalysis?: boolean;
+};
+/**
+ * Scalar plugin. This plugin provides an API reference interface for your API.
+ * @param options Scalar plugin options
+ * @returns Scalar plugin instance
+ */
+export declare class ScalarPlugin extends ShokupanRouter<any> implements ShokupanPlugin {
+    private readonly pluginOptions;
+    constructor(pluginOptions?: ScalarPluginOptions);
+    onInit(app: Shokupan, options?: ShokupanPluginOptions): void;
+    private init;
+    onMount(parent: ShokupanRouter<any>): void;
+}

package/dist/plugins/middleware/compression.d.ts

@@ -0,0 +1,17 @@
+import { Middleware } from '../../util/types';
+export interface CompressionOptions {
+    /**
+     * Minimum byte size to compress
+     */
+    threshold?: number;
+    /**
+     * Allowed algorithms
+     */
+    allowedAlgorithms?: string[];
+}
+/**
+ * Compression middleware.
+ * @param options Compression options
+ * @returns Middleware function
+ */
+export declare function Compression(options?: CompressionOptions): Middleware;

package/dist/plugins/middleware/cors.d.ts

@@ -0,0 +1,34 @@
+import { ShokupanContext } from '../../context';
+import { Middleware } from '../../util/types';
+export interface CorsOptions {
+    /**
+     * Origin to allow. Can be a string, array of strings, or function that returns a string.
+     */
+    origin?: string | string[] | ((ctx: ShokupanContext) => string | undefined | null | boolean);
+    /**
+     * HTTP methods to allow.
+     */
+    methods?: string | string[];
+    /**
+     * HTTP headers to allow.
+     */
+    allowedHeaders?: string | string[];
+    /**
+     * HTTP headers to expose.
+     */
+    exposedHeaders?: string | string[];
+    /**
+     * Whether to allow credentials.
+     */
+    credentials?: boolean;
+    /**
+     * Maximum age of preflight request.
+     */
+    maxAge?: number;
+}
+/**
+ * CORS middleware.
+ * @param options CORS options
+ * @returns Middleware function
+ */
+export declare function Cors(options?: CorsOptions): Middleware;

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

@@ -1,4 +1,4 @@
-import { Middleware } from '../types';
+import { Middleware } from '../../util/types';
 /**
  * Adapter to use legacy Express middleware.
  * NOTE: This provides a PARTIAL mock of req/res.

package/dist/plugins/{openapi-validator.d.ts → middleware/openapi-validator.d.ts}

@@ -1,4 +1,4 @@
-import { Middleware } from '../types';
+import { Middleware } from '../../util/types';
 type ValidatorCache = Map<string, {
     [method: string]: {
         body?: import('ajv').ValidateFunction;
@@ -26,5 +26,5 @@ export declare function precompileValidators(app: any, spec: any): void;
  *
  * @param app The Shokupan application instance
  */
-export declare function enableOpenApiValidation(app: import('../shokupan').Shokupan): void;
+export declare function enableOpenApiValidation(app: import('../../shokupan').Shokupan): void;
 export {};

package/dist/plugins/middleware/proxy.d.ts

@@ -0,0 +1,37 @@
+import { Middleware } from '../../util/types';
+export interface ProxyOptions {
+    /**
+     * Target URL to proxy requests to.
+     */
+    target: string;
+    /**
+     * Function to rewrite the path of the request.
+     */
+    pathRewrite?: (path: string) => string;
+    /**
+     * Whether to change the origin of the request.
+     */
+    changeOrigin?: boolean;
+    /**
+     * Whether to proxy WebSocket connections.
+     */
+    ws?: boolean;
+    /**
+     * Additional headers to send with the request.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Whitelist of allowed target hosts.
+     */
+    allowedHosts?: string[];
+    /**
+     * Whether to allow private IPs (disabled by default).
+     */
+    allowPrivateIPs?: boolean;
+}
+/**
+ * Proxy middleware. This will proxy requests that match the path to the target URL.
+ * @param options Proxy options
+ * @returns Middleware function
+ */
+export declare function Proxy(options: ProxyOptions): Middleware;

package/dist/plugins/middleware/rate-limit.d.ts

@@ -0,0 +1,58 @@
+import { ShokupanContext } from '../../context';
+import { Middleware } from '../../util/types';
+export interface RateLimitOptions {
+    /**
+     * Window in milliseconds
+     */
+    windowMs?: number;
+    /**
+     * Maximum number of requests allowed in the window
+     */
+    max?: number;
+    /**
+     * Alias for max
+     */
+    limit?: number;
+    /**
+     * Message to send when rate limited
+     */
+    message?: string | object | ((ctx: ShokupanContext, key: string) => string | object);
+    /**
+     * Status code to send when rate limited
+     */
+    statusCode?: number;
+    /**
+     * Whether to include X-RateLimit headers in the response
+     */
+    headers?: boolean;
+    /**
+     * Function to generate a unique key for each request
+     * This is used to identify the user or source of the request
+     * Defaults to the request's ip address.
+     */
+    keyGenerator?: (ctx: ShokupanContext) => string;
+    /**
+     * Function to execute when a request is rate limited
+     */
+    onRateLimited?: (ctx: ShokupanContext, key: string) => void | Response | Promise<void | Response>;
+    /**
+     * Function to determine whether to skip rate limiting
+     */
+    skip?: (ctx: ShokupanContext) => boolean;
+    /**
+     * Mode to use for rate limiting
+     * - user: Rate limit per user (generated key, defaults to ip address)
+     * - absolute: Rate limit for all users
+     */
+    mode?: 'user' | 'absolute';
+    /**
+     * List of trusted proxy IPs
+     */
+    trustedProxies?: string[];
+}
+/**
+ * Rate limit middleware.
+ * @param options Rate limit options
+ * @returns Middleware function
+ */
+export declare function RateLimitMiddleware(options?: RateLimitOptions): Middleware;

package/dist/plugins/{security-headers.d.ts → middleware/security-headers.d.ts}

@@ -1,36 +1,86 @@
-import { Middleware } from '../types';
+import { Middleware } from '../../util/types';
 export interface SecurityHeadersOptions {
+    /**
+     * Content Security Policy
+     */
     contentSecurityPolicy?: boolean | Record<string, any>;
+    /**
+     * Cross-Origin Embedder Policy
+     */
     crossOriginEmbedderPolicy?: boolean;
+    /**
+     * Cross-Origin Opener Policy
+     */
     crossOriginOpenerPolicy?: boolean;
+    /**
+     * Cross-Origin Resource Policy
+     */
     crossOriginResourcePolicy?: boolean;
+    /**
+     * DNS Prefetch Control
+     */
     dnsPrefetchControl?: boolean | {
         allow: boolean;
     };
+    /**
+     * Expect CT
+     */
     expectCt?: boolean | {
         maxAge?: number;
         enforce?: boolean;
         reportUri?: string;
     };
+    /**
+     * Frameguard
+     */
     frameguard?: boolean | {
         action: 'deny' | 'sameorigin' | 'allow-from';
         domain?: string;
     };
+    /**
+     * Hide Powered By
+     */
     hidePoweredBy?: boolean;
+    /**
+     * HTTP Strict Transport Security
+     */
     hsts?: boolean | {
         maxAge?: number;
         includeSubDomains?: boolean;
         preload?: boolean;
     };
+    /**
+     * IE No Open
+     */
     ieNoOpen?: boolean;
+    /**
+     * No Sniff
+     */
     noSniff?: boolean;
+    /**
+     * Origin Agent Cluster
+     */
     originAgentCluster?: boolean;
+    /**
+     * Permitted Cross Domain Policies
+     */
     permittedCrossDomainPolicies?: boolean | {
         permittedPolicies: 'none' | 'master-only' | 'by-content-type' | 'all';
     };
+    /**
+     * Referrer Policy
+     */
     referrerPolicy?: boolean | {
         policy: string | string[];
     };
+    /**
+     * X-XSS-Protection
+     */
     xssFilter?: boolean;
 }
+/**
+ * Security headers middleware.
+ * @param options Security headers options
+ * @returns Middleware function
+ */
 export declare function SecurityHeaders(options?: SecurityHeadersOptions): Middleware;

package/dist/plugins/{serve-static.d.ts → middleware/serve-static.d.ts}

@@ -1,2 +1,2 @@
-import { Middleware, StaticServeOptions } from '../types';
+import { Middleware, StaticServeOptions } from '../../util/types';
 export declare function serveStatic<T extends Record<string, any>>(config: StaticServeOptions<T>, prefix: string): Middleware;

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