@veloxts/router 0.6.84 → 0.6.86

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @veloxts/router
 
+## 0.6.86
+
+### Patch Changes
+
+- updated documentation
+- Updated dependencies
+  - @veloxts/core@0.6.86
+  - @veloxts/validation@0.6.86
+
+## 0.6.85
+
+### Patch Changes
+
+- implement missing features from original requirements
+- Updated dependencies
+  - @veloxts/core@0.6.85
+  - @veloxts/validation@0.6.85
+
 ## 0.6.84
 
 ### Patch Changes

package/GUIDE.md

@@ -134,19 +134,38 @@ await registerRestRoutes(app.server, {
 });
 ```
 
+### REST Route Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `prefix` | `string` | `'/api'` | URL prefix for all routes |
+| `procedures` | `Record<string, ProcedureCollection>` | required | Procedure collections to register |
+| `shortcuts` | `boolean` | `false` | Generate flat shortcut routes in addition to nested routes |
+| `nestingWarnings` | `boolean` | `true` | Warn when nesting depth exceeds 3 levels |
+
+When `shortcuts: true`, deeply nested resources also get flat access routes:
+```typescript
+// With shortcuts enabled:
+// GET /organizations/:orgId/projects/:projectId/tasks/:id (nested)
+// GET /tasks/:id (flat shortcut)
+```
+
 ## tRPC Adapter
 
 ```typescript
-import { trpc, appRouter, registerTRPCPlugin } from '@veloxts/router';
+import { trpc, appRouter, registerTRPCPlugin, type TRPCRouter } from '@veloxts/router';
 
 const t = trpc();
 const router = appRouter(t, [userProcedures]);
 
 await registerTRPCPlugin(app.server, { router, prefix: '/trpc' });
 
-export type AppRouter = typeof router;
+// Use TRPCRouter for @trpc/react-query compatibility
+export type AppRouter = TRPCRouter<typeof router>;
 ```
 
+> **Note**: `AsTRPCRouter` is deprecated. Use `TRPCRouter` instead.
+
 ## OpenAPI Documentation
 
 Auto-generate OpenAPI 3.0.3 specifications from your procedure definitions and serve interactive Swagger UI documentation.
@@ -221,14 +240,17 @@ await registerDocs(app.server, {
 });
 ```
 
-### CLI Command
+### CLI Commands
 
-Generate OpenAPI specs from the command line:
+Generate and serve OpenAPI specs from the command line:
 
 ```bash
 # Basic generation
 velox openapi generate --output ./openapi.json
 
+# YAML output (auto-detected from extension)
+velox openapi generate -o ./docs/api.yaml
+
 # Full options
 velox openapi generate \
   --path ./src/procedures \
@@ -236,14 +258,36 @@ velox openapi generate \
   --title "My API" \
   --version "1.0.0" \
   --description "API documentation" \
-  --server http://localhost:3030 \
-  --server https://api.example.com \
-  --prefix /api
+  --server "http://localhost:3030|Development" \
+  --server "https://api.example.com|Production" \
+  --prefix /api \
+  --recursive \
+  --pretty
 
 # Serve documentation locally
 velox openapi serve --port 8080
+
+# Serve with hot-reload on file changes
+velox openapi serve --watch -f ./docs/api.yaml
 ```
 
+**Available Options:**
+
+`velox openapi generate`:
+- `-p, --path <path>` - Procedures directory (default: `./src/procedures`)
+- `-o, --output <file>` - Output file path (default: `./openapi.json`)
+- `-f, --format <format>` - Output format: `json` or `yaml` (auto-detected from extension)
+- `-s, --server <url>` - Server URL (format: `url|description`, repeatable)
+- `--prefix <prefix>` - API route prefix (default: `/api`)
+- `-r, --recursive` - Scan subdirectories for procedures
+- `-q, --quiet` - Suppress output except errors
+
+`velox openapi serve`:
+- `-f, --file <file>` - OpenAPI spec file (default: `./openapi.json`)
+- `--port <port>` - Server port (default: `8080`)
+- `--host <host>` - Host to bind (default: `localhost`)
+- `-w, --watch` - Watch for file changes and hot-reload
+
 ### Security Schemes
 
 Guards are automatically mapped to OpenAPI security requirements:

package/dist/expose.d.ts

@@ -7,7 +7,7 @@
  * @module serve
  */
 import { type VeloxApp } from '@veloxts/core';
-import { type AnyRouter } from './trpc/index.js';
+import { type AnyRouter, type InferRouterFromCollections } from './trpc/index.js';
 import type { ProcedureCollection } from './types.js';
 /**
  * Options for serving procedures
@@ -38,38 +38,41 @@ export interface ServeOptions {
  * This is the recommended way to register your API.
  * Define your procedures once, serve them everywhere.
  *
+ * **IMPORTANT**: Use `as const` on the procedures array to preserve
+ * literal types for full type inference on the returned router.
+ *
  * @param app - VeloxTS application instance
- * @param procedures - Array of procedure collections to serve
+ * @param procedures - Array of procedure collections to serve (use `as const`)
  * @param options - Optional configuration for API and RPC prefixes
- * @returns The tRPC router for type exports
+ * @returns The typed tRPC router for type exports
  *
  * @example
  * ```typescript
  * // Both REST (/api) and tRPC (/trpc) with zero config
- * const router = await serve(app, [healthProcedures, userProcedures]);
- * export type AppRouter = typeof router;
+ * const router = await serve(app, [healthProcedures, userProcedures] as const);
+ * export type AppRouter = typeof router; // Fully typed!
  * ```
  *
  * @example
  * ```typescript
  * // REST only (external API)
- * await serve(app, [healthProcedures, userProcedures], { rpc: false });
+ * await serve(app, [healthProcedures, userProcedures] as const, { rpc: false });
  * ```
  *
  * @example
  * ```typescript
  * // tRPC only (internal app)
- * const router = await serve(app, [healthProcedures, userProcedures], { api: false });
+ * const router = await serve(app, [healthProcedures, userProcedures] as const, { api: false });
  * export type AppRouter = typeof router;
  * ```
  *
  * @example
  * ```typescript
  * // Custom prefixes
- * const router = await serve(app, [healthProcedures, userProcedures], {
+ * const router = await serve(app, [healthProcedures, userProcedures] as const, {
  *   api: '/v1',
  *   rpc: '/rpc',
  * });
  * ```
  */
-export declare function serve(app: VeloxApp, procedures: ProcedureCollection[], options?: ServeOptions): Promise<AnyRouter>;
+export declare function serve<const T extends readonly ProcedureCollection[]>(app: VeloxApp, procedures: T, options?: ServeOptions): Promise<AnyRouter & InferRouterFromCollections<T>>;

package/dist/expose.js

@@ -8,7 +8,7 @@
  */
 import { fail } from '@veloxts/core';
 import { rest } from './rest/index.js';
-import { appRouter, registerTRPCPlugin, trpc } from './trpc/index.js';
+import { appRouter, registerTRPCPlugin, trpc, } from './trpc/index.js';
 // ============================================================================
 // Main Function
 // ============================================================================
@@ -18,35 +18,38 @@ import { appRouter, registerTRPCPlugin, trpc } from './trpc/index.js';
  * This is the recommended way to register your API.
  * Define your procedures once, serve them everywhere.
  *
+ * **IMPORTANT**: Use `as const` on the procedures array to preserve
+ * literal types for full type inference on the returned router.
+ *
  * @param app - VeloxTS application instance
- * @param procedures - Array of procedure collections to serve
+ * @param procedures - Array of procedure collections to serve (use `as const`)
  * @param options - Optional configuration for API and RPC prefixes
- * @returns The tRPC router for type exports
+ * @returns The typed tRPC router for type exports
  *
  * @example
  * ```typescript
  * // Both REST (/api) and tRPC (/trpc) with zero config
- * const router = await serve(app, [healthProcedures, userProcedures]);
- * export type AppRouter = typeof router;
+ * const router = await serve(app, [healthProcedures, userProcedures] as const);
+ * export type AppRouter = typeof router; // Fully typed!
  * ```
  *
  * @example
  * ```typescript
  * // REST only (external API)
- * await serve(app, [healthProcedures, userProcedures], { rpc: false });
+ * await serve(app, [healthProcedures, userProcedures] as const, { rpc: false });
  * ```
  *
  * @example
  * ```typescript
  * // tRPC only (internal app)
- * const router = await serve(app, [healthProcedures, userProcedures], { api: false });
+ * const router = await serve(app, [healthProcedures, userProcedures] as const, { api: false });
  * export type AppRouter = typeof router;
  * ```
  *
  * @example
  * ```typescript
  * // Custom prefixes
- * const router = await serve(app, [healthProcedures, userProcedures], {
+ * const router = await serve(app, [healthProcedures, userProcedures] as const, {
  *   api: '/v1',
  *   rpc: '/rpc',
  * });
@@ -73,7 +76,8 @@ export async function serve(app, procedures, options = {}) {
     }
     // Register REST routes if enabled
     if (apiPrefix !== false) {
-        app.routes(rest(procedures, { prefix: apiPrefix }));
+        // Need to spread to convert readonly tuple to mutable array for rest()
+        app.routes(rest([...procedures], { prefix: apiPrefix }));
     }
     return router;
 }

package/dist/index.d.ts

@@ -39,7 +39,7 @@
  */
 /** Router package version */
 export declare const ROUTER_VERSION: string;
-export type { CompiledProcedure, ContextExtensions, ContextFactory, ExtendedContext, GuardLike, HttpMethod, InferProcedureContext, InferProcedureInput, InferProcedureOutput, InferProcedureTypes, MiddlewareArgs, MiddlewareFunction, MiddlewareNext, MiddlewareResult, ParentResourceConfig, ProcedureCollection, ProcedureHandler, ProcedureHandlerArgs, ProcedureRecord, ProcedureType, RestRouteOverride, } from './types.js';
+export type { CompiledProcedure, ContextExtensions, ContextFactory, ExtendedContext, GuardLike, HttpMethod, InferProcedureContext, InferProcedureInput, InferProcedureOutput, InferProcedureTypes, MiddlewareArgs, MiddlewareFunction, MiddlewareNext, MiddlewareResult, ParentResourceChain, ParentResourceConfig, ProcedureCollection, ProcedureHandler, ProcedureHandlerArgs, ProcedureRecord, ProcedureType, RestRouteOverride, } from './types.js';
 export { PROCEDURE_METHOD_MAP, } from './types.js';
 export type { GuardErrorResponse, RouterErrorCode } from './errors.js';
 export { GuardError, isGuardError } from './errors.js';
@@ -51,10 +51,14 @@ export type { RouterResult } from './router-utils.js';
 export { createRouter, toRouter } from './router-utils.js';
 export type { NamingWarning, NamingWarningType, WarningConfig, WarningOption } from './warnings.js';
 export { analyzeNamingConvention, isDevelopment, normalizeWarningOption } from './warnings.js';
-export type { ExtractRoutesType, RestAdapterOptions, RestMapping, RestRoute, RouteMap, } from './rest/index.js';
-export { buildNestedRestPath, buildRestPath, extractRoutes, followsNamingConvention, generateRestRoutes, getRouteSummary, inferResourceName, parseNamingConvention, registerRestRoutes, rest, } from './rest/index.js';
-export type { AnyRouter, InferAppRouter, TRPCInstance, TRPCPluginOptions, } from './trpc/index.js';
+export type { ExtractRoutesType, GenerateRestRoutesOptions, RestAdapterOptions, RestMapping, RestRoute, RouteMap, } from './rest/index.js';
+export { buildMultiLevelNestedPath, buildNestedRestPath, buildRestPath, calculateNestingDepth, extractRoutes, followsNamingConvention, generateRestRoutes, getRouteSummary, inferResourceName, parseNamingConvention, registerRestRoutes, rest, } from './rest/index.js';
+export type { AnyRouter, 
+/** @deprecated Use `TRPCRouter` instead */
+AsTRPCRouter, CollectionsToRouterRecord, ExtractNamespace, ExtractProcedures, InferAppRouter, InferRouterFromCollections, MapProcedureRecordToTRPC, MapProcedureToTRPC, TRPCInstance, TRPCPluginOptions, TRPCRouter, } from './trpc/index.js';
 export { appRouter, buildTRPCRouter, createTRPCContextFactory, registerTRPCPlugin, trpc, veloxErrorToTRPCError, } from './trpc/index.js';
+export type { RpcOptions, RpcResult } from './rpc.js';
+export { registerRpc, rpc } from './rpc.js';
 export type { DiscoveryOptions, DiscoveryResult, DiscoveryWarning } from './discovery/index.js';
 export { DiscoveryError, DiscoveryErrorCode, directoryNotFound, discoverProcedures, discoverProceduresVerbose, fileLoadError, invalidExport, invalidFileType, isDiscoveryError, noProceduresFound, permissionDenied, } from './discovery/index.js';
 export type { ServeOptions } from './expose.js';
@@ -101,5 +105,5 @@ export { APP_ROUTER, PROCEDURE_COLLECTIONS, REST_ADAPTER_CONFIG, ROUTER_CONFIG,
  * });
  * ```
  */
-export type { BuildParametersOptions, BuildParametersResult, GuardMappingOptions, JSONSchema, OpenAPIComponents, OpenAPIContact, OpenAPIEncoding, OpenAPIExample, OpenAPIExternalDocs, OpenAPIGeneratorOptions, OpenAPIHeader, OpenAPIHttpMethod, OpenAPIInfo, OpenAPILicense, OpenAPILink, OpenAPIMediaType, OpenAPIOAuthFlow, OpenAPIOAuthFlows, OpenAPIOperation, OpenAPIParameter, OpenAPIPathItem, OpenAPIRequestBody, OpenAPIResponse, OpenAPISecurityRequirement, OpenAPISecurityScheme, OpenAPIServer, OpenAPISpec, OpenAPITag, ParameterIn, QueryParamExtractionOptions, RouteInfo, SchemaConversionOptions, SecuritySchemeType, SwaggerUIConfig, SwaggerUIPluginOptions, } from './openapi/index.js';
-export { buildParameters, convertFromOpenAPIPath, convertToOpenAPIPath, createSecurityRequirement, createStringSchema, createSwaggerUI, DEFAULT_GUARD_MAPPINGS, DEFAULT_SECURITY_SCHEMES, extractGuardScopes, extractPathParamNames, extractQueryParameters, extractResourceFromPath, extractSchemaProperties, extractUsedSecuritySchemes, filterUsedSecuritySchemes, generateOpenApiSpec, getOpenApiRouteSummary, getOpenApiSpec, guardsRequireAuth, guardsToSecurity, hasPathParameters, joinPaths, mapGuardToSecurity, mergeSchemas, mergeSecuritySchemes, normalizePath, parsePathParameters, registerDocs, removeSchemaProperties, schemaHasProperties, swaggerUIPlugin, validateOpenApiSpec, zodSchemaToJsonSchema, } from './openapi/index.js';
+export type { BuildParametersOptions, BuildParametersResult, GuardMappingOptions, JSONSchema, OpenAPIComponents, OpenAPIContact, OpenAPIEncoding, OpenAPIExample, OpenAPIExternalDocs, OpenAPIGeneratorOptions, OpenAPIHeader, OpenAPIHttpMethod, OpenAPIInfo, OpenAPILicense, OpenAPILink, OpenAPIMediaType, OpenAPIOAuthFlow, OpenAPIOAuthFlows, OpenAPIOperation, OpenAPIParameter, OpenAPIPathItem, OpenAPIRequestBody, OpenAPIResponse, OpenAPISecurityRequirement, OpenAPISecurityScheme, OpenAPIServer, OpenAPISpec, OpenAPITag, ParameterIn, QueryParamExtractionOptions, RouteInfo, SchemaConversionOptions, SecuritySchemeType, SwaggerUIConfig, SwaggerUIHtmlOptions, SwaggerUIPluginOptions, } from './openapi/index.js';
+export { buildParameters, convertFromOpenAPIPath, convertToOpenAPIPath, createSecurityRequirement, createStringSchema, createSwaggerUI, DEFAULT_GUARD_MAPPINGS, DEFAULT_SECURITY_SCHEMES, DEFAULT_UI_CONFIG, escapeHtml, extractGuardScopes, extractPathParamNames, extractQueryParameters, extractResourceFromPath, extractSchemaProperties, extractUsedSecuritySchemes, filterUsedSecuritySchemes, generateOpenApiSpec, generateSwaggerUIHtml, getOpenApiRouteSummary, getOpenApiSpec, guardsRequireAuth, guardsToSecurity, hasPathParameters, joinPaths, mapGuardToSecurity, mergeSchemas, mergeSecuritySchemes, normalizePath, parsePathParameters, registerDocs, removeSchemaProperties, SWAGGER_UI_CDN, schemaHasProperties, swaggerUIPlugin, validateOpenApiSpec, zodSchemaToJsonSchema, } from './openapi/index.js';

package/dist/index.js

@@ -58,10 +58,11 @@ defineProcedures, executeProcedure, isCompiledProcedure, isProcedureCollection,
 export { createProcedure, typedProcedure } from './procedure/factory.js';
 export { createRouter, toRouter } from './router-utils.js';
 export { analyzeNamingConvention, isDevelopment, normalizeWarningOption } from './warnings.js';
-export { buildNestedRestPath, buildRestPath, extractRoutes, followsNamingConvention, generateRestRoutes, getRouteSummary, inferResourceName, parseNamingConvention, registerRestRoutes, rest, } from './rest/index.js';
+export { buildMultiLevelNestedPath, buildNestedRestPath, buildRestPath, calculateNestingDepth, extractRoutes, followsNamingConvention, generateRestRoutes, getRouteSummary, inferResourceName, parseNamingConvention, registerRestRoutes, rest, } from './rest/index.js';
 export { 
 // tRPC utilities
 appRouter, buildTRPCRouter, createTRPCContextFactory, registerTRPCPlugin, trpc, veloxErrorToTRPCError, } from './trpc/index.js';
+export { registerRpc, rpc } from './rpc.js';
 export { DiscoveryError, DiscoveryErrorCode, directoryNotFound, discoverProcedures, discoverProceduresVerbose, fileLoadError, invalidExport, invalidFileType, isDiscoveryError, noProceduresFound, permissionDenied, } from './discovery/index.js';
 export { serve } from './expose.js';
 // ============================================================================
@@ -97,6 +98,8 @@ createSecurityRequirement,
 // Schema converter
 createStringSchema, 
 // Plugin
-createSwaggerUI, DEFAULT_GUARD_MAPPINGS, DEFAULT_SECURITY_SCHEMES, extractGuardScopes, extractPathParamNames, extractQueryParameters, extractResourceFromPath, extractSchemaProperties, extractUsedSecuritySchemes, filterUsedSecuritySchemes, 
+createSwaggerUI, DEFAULT_GUARD_MAPPINGS, DEFAULT_SECURITY_SCHEMES, DEFAULT_UI_CONFIG, escapeHtml, extractGuardScopes, extractPathParamNames, extractQueryParameters, extractResourceFromPath, extractSchemaProperties, extractUsedSecuritySchemes, filterUsedSecuritySchemes, 
 // Generator
-generateOpenApiSpec, getOpenApiRouteSummary, getOpenApiSpec, guardsRequireAuth, guardsToSecurity, hasPathParameters, joinPaths, mapGuardToSecurity, mergeSchemas, mergeSecuritySchemes, normalizePath, parsePathParameters, registerDocs, removeSchemaProperties, schemaHasProperties, swaggerUIPlugin, validateOpenApiSpec, zodSchemaToJsonSchema, } from './openapi/index.js';
+generateOpenApiSpec, 
+// HTML Generator
+generateSwaggerUIHtml, getOpenApiRouteSummary, getOpenApiSpec, guardsRequireAuth, guardsToSecurity, hasPathParameters, joinPaths, mapGuardToSecurity, mergeSchemas, mergeSecuritySchemes, normalizePath, parsePathParameters, registerDocs, removeSchemaProperties, SWAGGER_UI_CDN, schemaHasProperties, swaggerUIPlugin, validateOpenApiSpec, zodSchemaToJsonSchema, } from './openapi/index.js';

package/dist/middleware/chain.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Shared middleware chain execution utility
+ *
+ * Provides a single implementation for executing middleware chains,
+ * used by both the procedure builder and tRPC adapter.
+ *
+ * @module middleware/chain
+ */
+import type { BaseContext } from '@veloxts/core';
+import type { MiddlewareFunction } from '../types.js';
+/**
+ * Result wrapper for middleware chain execution
+ */
+export interface MiddlewareResult<TOutput> {
+    output: TOutput;
+}
+/**
+ * Execute a middleware chain with the given handler
+ *
+ * Builds the chain from end to start and executes it, allowing each
+ * middleware to extend the context before calling the next middleware.
+ *
+ * @param middlewares - Array of middleware functions to execute
+ * @param input - The input to pass to each middleware
+ * @param ctx - The context object (will be mutated by middleware)
+ * @param handler - The final handler to execute after all middleware
+ * @returns The output from the handler
+ *
+ * @example
+ * ```typescript
+ * const result = await executeMiddlewareChain(
+ *   procedure.middlewares,
+ *   input,
+ *   ctx,
+ *   async () => handler({ input, ctx })
+ * );
+ * ```
+ */
+export declare function executeMiddlewareChain<TInput, TOutput, TContext extends BaseContext>(middlewares: ReadonlyArray<MiddlewareFunction<TInput, TContext, TContext, TOutput>>, input: TInput, ctx: TContext, handler: () => Promise<TOutput>): Promise<TOutput>;
+/**
+ * Create a precompiled middleware executor for a fixed middleware chain
+ *
+ * This is an optimization that builds the chain structure once during
+ * procedure compilation, creating a reusable function that can execute
+ * the chain without rebuilding closures on every request.
+ *
+ * @param middlewares - Array of middleware functions
+ * @param handler - The procedure handler (can return sync or async)
+ * @returns A function that executes the full chain
+ */
+export declare function createMiddlewareExecutor<TInput, TOutput, TContext extends BaseContext>(middlewares: ReadonlyArray<MiddlewareFunction<TInput, TContext, TContext, TOutput>>, handler: (params: {
+    input: TInput;
+    ctx: TContext;
+}) => TOutput | Promise<TOutput>): (input: TInput, ctx: TContext) => Promise<TOutput>;

package/dist/middleware/chain.js

@@ -0,0 +1,80 @@
+/**
+ * Shared middleware chain execution utility
+ *
+ * Provides a single implementation for executing middleware chains,
+ * used by both the procedure builder and tRPC adapter.
+ *
+ * @module middleware/chain
+ */
+/**
+ * Execute a middleware chain with the given handler
+ *
+ * Builds the chain from end to start and executes it, allowing each
+ * middleware to extend the context before calling the next middleware.
+ *
+ * @param middlewares - Array of middleware functions to execute
+ * @param input - The input to pass to each middleware
+ * @param ctx - The context object (will be mutated by middleware)
+ * @param handler - The final handler to execute after all middleware
+ * @returns The output from the handler
+ *
+ * @example
+ * ```typescript
+ * const result = await executeMiddlewareChain(
+ *   procedure.middlewares,
+ *   input,
+ *   ctx,
+ *   async () => handler({ input, ctx })
+ * );
+ * ```
+ */
+export async function executeMiddlewareChain(middlewares, input, ctx, handler) {
+    // Build the chain from the end (handler) back to the start
+    let next = async () => {
+        const output = await handler();
+        return { output };
+    };
+    // Wrap each middleware from last to first
+    for (let i = middlewares.length - 1; i >= 0; i--) {
+        const middleware = middlewares[i];
+        const currentNext = next;
+        next = async () => {
+            return middleware({
+                input,
+                ctx,
+                next: async (opts) => {
+                    // Allow middleware to extend context
+                    if (opts?.ctx) {
+                        Object.assign(ctx, opts.ctx);
+                    }
+                    return currentNext();
+                },
+            });
+        };
+    }
+    const result = await next();
+    return result.output;
+}
+/**
+ * Create a precompiled middleware executor for a fixed middleware chain
+ *
+ * This is an optimization that builds the chain structure once during
+ * procedure compilation, creating a reusable function that can execute
+ * the chain without rebuilding closures on every request.
+ *
+ * @param middlewares - Array of middleware functions
+ * @param handler - The procedure handler (can return sync or async)
+ * @returns A function that executes the full chain
+ */
+export function createMiddlewareExecutor(middlewares, handler) {
+    // If no middlewares, just return a direct handler call
+    if (middlewares.length === 0) {
+        return async (input, ctx) => {
+            return handler({ input, ctx });
+        };
+    }
+    // Return an executor that uses the shared chain execution
+    return async (input, ctx) => {
+        return executeMiddlewareChain(middlewares, input, ctx, async () => handler({ input, ctx }));
+    };
+}

package/dist/middleware/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Middleware utilities
+ *
+ * @module middleware
+ */
+export type { MiddlewareResult } from './chain.js';
+export { createMiddlewareExecutor, executeMiddlewareChain } from './chain.js';

package/dist/middleware/index.js

@@ -0,0 +1,6 @@
+/**
+ * Middleware utilities
+ *
+ * @module middleware
+ */
+export { createMiddlewareExecutor, executeMiddlewareChain } from './chain.js';

package/dist/openapi/generator.js

@@ -147,6 +147,16 @@ function generateOperation(route, namespace, options) {
     if (security.length > 0) {
         operation.security = security;
     }
+    // Add deprecation flag
+    if (procedure.deprecated) {
+        operation.deprecated = true;
+        // Add deprecation message as description suffix if present
+        if (procedure.deprecationMessage) {
+            operation.description = operation.description
+                ? `${operation.description}\n\n**Deprecated:** ${procedure.deprecationMessage}`
+                : `**Deprecated:** ${procedure.deprecationMessage}`;
+        }
+    }
     return operation;
 }
 // ============================================================================

package/dist/openapi/html-generator.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Swagger UI HTML Generator
+ *
+ * Generates standalone Swagger UI HTML pages for displaying OpenAPI specifications.
+ * This module is used by both the Fastify plugin and CLI serve command.
+ *
+ * @module @veloxts/router/openapi/html-generator
+ */
+import type { SwaggerUIConfig } from './types.js';
+/**
+ * Default Swagger UI configuration
+ */
+export declare const DEFAULT_UI_CONFIG: SwaggerUIConfig;
+/**
+ * Swagger UI CDN URLs
+ */
+export declare const SWAGGER_UI_CDN: {
+    css: string;
+    bundle: string;
+    standalonePreset: string;
+};
+/**
+ * Options for generating Swagger UI HTML
+ */
+export interface SwaggerUIHtmlOptions {
+    /**
+     * URL where the OpenAPI spec can be fetched
+     */
+    specUrl: string;
+    /**
+     * Page title
+     * @default 'API Documentation'
+     */
+    title?: string;
+    /**
+     * Custom favicon URL
+     */
+    favicon?: string;
+    /**
+     * Swagger UI configuration options
+     */
+    config?: Partial<SwaggerUIConfig>;
+}
+/**
+ * Generates a standalone Swagger UI HTML page
+ *
+ * @param options - HTML generation options
+ * @returns Complete HTML document as string
+ *
+ * @example
+ * ```typescript
+ * const html = generateSwaggerUIHtml({
+ *   specUrl: '/openapi.json',
+ *   title: 'My API Documentation',
+ *   config: { tryItOutEnabled: true },
+ * });
+ * ```
+ */
+export declare function generateSwaggerUIHtml(options: SwaggerUIHtmlOptions): string;
+/**
+ * Escapes HTML special characters to prevent XSS
+ *
+ * @param text - Text to escape
+ * @returns Escaped text
+ */
+export declare function escapeHtml(text: string): string;

package/dist/openapi/html-generator.js

@@ -0,0 +1,116 @@
+/**
+ * Swagger UI HTML Generator
+ *
+ * Generates standalone Swagger UI HTML pages for displaying OpenAPI specifications.
+ * This module is used by both the Fastify plugin and CLI serve command.
+ *
+ * @module @veloxts/router/openapi/html-generator
+ */
+// ============================================================================
+// Constants
+// ============================================================================
+/**
+ * Default Swagger UI configuration
+ */
+export const DEFAULT_UI_CONFIG = {
+    deepLinking: true,
+    displayOperationId: false,
+    defaultModelsExpandDepth: 1,
+    defaultModelExpandDepth: 1,
+    docExpansion: 'list',
+    filter: false,
+    showExtensions: false,
+    tryItOutEnabled: true,
+    persistAuthorization: false,
+};
+/**
+ * Swagger UI CDN URLs
+ */
+export const SWAGGER_UI_CDN = {
+    css: 'https://unpkg.com/swagger-ui-dist@5/swagger-ui.css',
+    bundle: 'https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js',
+    standalonePreset: 'https://unpkg.com/swagger-ui-dist@5/swagger-ui-standalone-preset.js',
+};
+// ============================================================================
+// HTML Generation
+// ============================================================================
+/**
+ * Generates a standalone Swagger UI HTML page
+ *
+ * @param options - HTML generation options
+ * @returns Complete HTML document as string
+ *
+ * @example
+ * ```typescript
+ * const html = generateSwaggerUIHtml({
+ *   specUrl: '/openapi.json',
+ *   title: 'My API Documentation',
+ *   config: { tryItOutEnabled: true },
+ * });
+ * ```
+ */
+export function generateSwaggerUIHtml(options) {
+    const { specUrl, title = 'API Documentation', favicon, config = {} } = options;
+    // Merge config with defaults
+    const mergedConfig = {
+        ...DEFAULT_UI_CONFIG,
+        ...config,
+    };
+    const configJson = JSON.stringify({
+        url: specUrl,
+        dom_id: '#swagger-ui',
+        deepLinking: mergedConfig.deepLinking,
+        displayOperationId: mergedConfig.displayOperationId,
+        defaultModelsExpandDepth: mergedConfig.defaultModelsExpandDepth,
+        defaultModelExpandDepth: mergedConfig.defaultModelExpandDepth,
+        docExpansion: mergedConfig.docExpansion,
+        filter: mergedConfig.filter,
+        showExtensions: mergedConfig.showExtensions,
+        tryItOutEnabled: mergedConfig.tryItOutEnabled,
+        persistAuthorization: mergedConfig.persistAuthorization,
+        presets: ['SwaggerUIBundle.presets.apis', 'SwaggerUIStandalonePreset'],
+        plugins: ['SwaggerUIBundle.plugins.DownloadUrl'],
+        layout: 'StandaloneLayout',
+    });
+    const faviconTag = favicon ? `<link rel="icon" type="image/x-icon" href="${favicon}">` : '';
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${escapeHtml(title)}</title>
+  ${faviconTag}
+  <link rel="stylesheet" href="${SWAGGER_UI_CDN.css}">
+  <style>
+    html { box-sizing: border-box; overflow-y: scroll; }
+    *, *:before, *:after { box-sizing: inherit; }
+    body { margin: 0; background: #fafafa; }
+    .swagger-ui .topbar { display: none; }
+  </style>
+</head>
+<body>
+  <div id="swagger-ui"></div>
+  <script src="${SWAGGER_UI_CDN.bundle}"></script>
+  <script src="${SWAGGER_UI_CDN.standalonePreset}"></script>
+  <script>
+    window.onload = function() {
+      window.ui = SwaggerUIBundle(${configJson.replace(/"(SwaggerUIBundle\.presets\.apis|SwaggerUIStandalonePreset|SwaggerUIBundle\.plugins\.DownloadUrl)"/g, '$1')});
+    };
+  </script>
+</body>
+</html>`;
+}
+/**
+ * Escapes HTML special characters to prevent XSS
+ *
+ * @param text - Text to escape
+ * @returns Escaped text
+ */
+export function escapeHtml(text) {
+    return text
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#039;');
+}