@veloxts/router 0.6.85 → 0.6.86

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @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

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/index.d.ts

@@ -105,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

@@ -98,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/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;');
+}

package/dist/openapi/index.d.ts

@@ -31,6 +31,7 @@
  */
 export { generateOpenApiSpec, getOpenApiRouteSummary, validateOpenApiSpec, } from './generator.js';
 export { createSwaggerUI, getOpenApiSpec, registerDocs, swaggerUIPlugin, } from './plugin.js';
+export { DEFAULT_UI_CONFIG, escapeHtml, generateSwaggerUIHtml, SWAGGER_UI_CDN, type SwaggerUIHtmlOptions, } from './html-generator.js';
 export { createStringSchema, extractSchemaProperties, mergeSchemas, removeSchemaProperties, type SchemaConversionOptions, schemaHasProperties, zodSchemaToJsonSchema, } from './schema-converter.js';
 export { type BuildParametersOptions, type BuildParametersResult, buildParameters, convertFromOpenAPIPath, convertToOpenAPIPath, extractPathParamNames, extractQueryParameters, extractResourceFromPath, hasPathParameters, joinPaths, normalizePath, parsePathParameters, type QueryParamExtractionOptions, } from './path-extractor.js';
 export { createSecurityRequirement, DEFAULT_GUARD_MAPPINGS, DEFAULT_SECURITY_SCHEMES, extractGuardScopes, extractUsedSecuritySchemes, filterUsedSecuritySchemes, type GuardMappingOptions, guardsRequireAuth, guardsToSecurity, mapGuardToSecurity, mergeSecuritySchemes, } from './security-mapper.js';

package/dist/openapi/index.js

@@ -38,6 +38,10 @@ export { generateOpenApiSpec, getOpenApiRouteSummary, validateOpenApiSpec, } fro
 // ============================================================================
 export { createSwaggerUI, getOpenApiSpec, registerDocs, swaggerUIPlugin, } from './plugin.js';
 // ============================================================================
+// HTML Generator
+// ============================================================================
+export { DEFAULT_UI_CONFIG, escapeHtml, generateSwaggerUIHtml, SWAGGER_UI_CDN, } from './html-generator.js';
+// ============================================================================
 // Schema Converter
 // ============================================================================
 export { createStringSchema, extractSchemaProperties, mergeSchemas, removeSchemaProperties, schemaHasProperties, zodSchemaToJsonSchema, } from './schema-converter.js';

package/dist/openapi/plugin.js

@@ -6,90 +6,7 @@
  * @module @veloxts/router/openapi/plugin
  */
 import { generateOpenApiSpec } from './generator.js';
-// ============================================================================
-// Swagger UI HTML Generation
-// ============================================================================
-/**
- * Default Swagger UI configuration
- */
-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
- */
-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',
-};
-/**
- * Generates the Swagger UI HTML page
- */
-function generateSwaggerUIHtml(specUrl, config, title, favicon) {
-    const configJson = JSON.stringify({
-        url: specUrl,
-        dom_id: '#swagger-ui',
-        deepLinking: config.deepLinking,
-        displayOperationId: config.displayOperationId,
-        defaultModelsExpandDepth: config.defaultModelsExpandDepth,
-        defaultModelExpandDepth: config.defaultModelExpandDepth,
-        docExpansion: config.docExpansion,
-        filter: config.filter,
-        showExtensions: config.showExtensions,
-        tryItOutEnabled: config.tryItOutEnabled,
-        persistAuthorization: config.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
- */
-function escapeHtml(text) {
-    return text
-        .replace(/&/g, '&amp;')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;')
-        .replace(/"/g, '&quot;')
-        .replace(/'/g, '&#039;');
-}
+import { generateSwaggerUIHtml } from './html-generator.js';
 // ============================================================================
 // Fastify Plugin
 // ============================================================================
@@ -118,11 +35,6 @@ function escapeHtml(text) {
  */
 export const swaggerUIPlugin = async (fastify, options) => {
     const { routePrefix = '/docs', specRoute = `${routePrefix}/openapi.json`, uiConfig = {}, openapi, collections, title = 'API Documentation', favicon, } = options;
-    // Merge UI config with defaults
-    const mergedConfig = {
-        ...DEFAULT_UI_CONFIG,
-        ...uiConfig,
-    };
     // Generate the OpenAPI specification
     let spec;
     try {
@@ -137,7 +49,12 @@ export const swaggerUIPlugin = async (fastify, options) => {
         return reply.header('Content-Type', 'application/json').send(spec);
     });
     // Register Swagger UI HTML route
-    const htmlContent = generateSwaggerUIHtml(specRoute, mergedConfig, title, favicon);
+    const htmlContent = generateSwaggerUIHtml({
+        specUrl: specRoute,
+        title,
+        favicon,
+        config: uiConfig,
+    });
     fastify.get(routePrefix, async (_request, reply) => {
         return reply.header('Content-Type', 'text/html; charset=utf-8').send(htmlContent);
     });

package/dist/procedure/builder.js

@@ -117,6 +117,8 @@ export function procedure() {
         restOverride: undefined,
         parentResource: undefined,
         parentResources: undefined,
+        deprecated: undefined,
+        deprecationMessage: undefined,
     });
 }
 // ============================================================================
@@ -210,6 +212,16 @@ function createBuilder(state) {
                 restOverride: config,
             });
         },
+        /**
+         * Marks the procedure as deprecated
+         */
+        deprecated(message) {
+            return createBuilder({
+                ...state,
+                deprecated: true,
+                deprecationMessage: message,
+            });
+        },
         /**
          * Declares a parent resource for nested routes (single level)
          */
@@ -275,6 +287,8 @@ function compileProcedure(type, handler, state) {
         middlewares: typedMiddlewares,
         guards: state.guards,
         restOverride: state.restOverride,
+        deprecated: state.deprecated,
+        deprecationMessage: state.deprecationMessage,
         parentResource: state.parentResource,
         parentResources: state.parentResources,
         // Store pre-compiled executor for performance

package/dist/procedure/types.d.ts

@@ -248,6 +248,29 @@ export interface ProcedureBuilder<TInput = unknown, TOutput = unknown, TContext
      * ```
      */
     rest(config: RestRouteOverride): ProcedureBuilder<TInput, TOutput, TContext>;
+    /**
+     * Marks the procedure as deprecated
+     *
+     * Deprecated procedures will be marked in OpenAPI documentation with the
+     * deprecated flag, helping API consumers know they should migrate to alternatives.
+     *
+     * @param message - Optional message explaining the deprecation and suggesting alternatives
+     * @returns Same builder (no type changes)
+     *
+     * @example
+     * ```typescript
+     * // Simple deprecation
+     * procedure()
+     *   .deprecated()
+     *   .query(handler);
+     *
+     * // With migration message
+     * procedure()
+     *   .deprecated('Use getUserById instead. This endpoint will be removed in v2.0.')
+     *   .query(handler);
+     * ```
+     */
+    deprecated(message?: string): ProcedureBuilder<TInput, TOutput, TContext>;
     /**
      * Declares a parent resource for nested routes (single level)
      *
@@ -368,6 +391,10 @@ export interface BuilderRuntimeState {
     parentResource?: ParentResourceConfig;
     /** Multi-level parent resource configuration for deeply nested routes */
     parentResources?: ParentResourceConfig[];
+    /** Whether this procedure is deprecated */
+    deprecated?: boolean;
+    /** Deprecation message */
+    deprecationMessage?: string;
 }
 /**
  * Type for the procedures object passed to defineProcedures

package/dist/types.d.ts

@@ -271,6 +271,10 @@ export interface CompiledProcedure<TInput = unknown, TOutput = unknown, TContext
     readonly guards: ReadonlyArray<GuardLike<TContext>>;
     /** REST route override (if specified) */
     readonly restOverride?: RestRouteOverride;
+    /** Whether this procedure is deprecated */
+    readonly deprecated?: boolean;
+    /** Deprecation message explaining why and what to use instead */
+    readonly deprecationMessage?: string;
     /**
      * Parent resource configuration for nested routes (single level)
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veloxts/router",
-  "version": "0.6.85",
+  "version": "0.6.86",
   "description": "Procedure definitions with tRPC and REST routing for VeloxTS framework",
   "type": "module",
   "main": "dist/index.js",
@@ -40,8 +40,8 @@
     "@trpc/server": "11.8.0",
     "fastify": "5.6.2",
     "zod-to-json-schema": "3.24.5",
-    "@veloxts/core": "0.6.85",
-    "@veloxts/validation": "0.6.85"
+    "@veloxts/validation": "0.6.86",
+    "@veloxts/core": "0.6.86"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "4.0.16",