@veloxts/router 0.6.84 → 0.6.86

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

@@ -9,6 +9,7 @@
  */
 import { ConfigurationError, logWarning } from '@veloxts/core';
 import { GuardError } from '../errors.js';
+import { createMiddlewareExecutor, executeMiddlewareChain } from '../middleware/chain.js';
 import { analyzeNamingConvention, isDevelopment, normalizeWarningOption, } from '../warnings.js';
 // ============================================================================
 // Utility Functions
@@ -115,6 +116,9 @@ export function procedure() {
         guards: [],
         restOverride: undefined,
         parentResource: undefined,
+        parentResources: undefined,
+        deprecated: undefined,
+        deprecationMessage: undefined,
     });
 }
 // ============================================================================
@@ -209,18 +213,41 @@ function createBuilder(state) {
             });
         },
         /**
-         * Declares a parent resource for nested routes
+         * Marks the procedure as deprecated
          */
-        parent(namespace, paramName) {
+        deprecated(message) {
+            return createBuilder({
+                ...state,
+                deprecated: true,
+                deprecationMessage: message,
+            });
+        },
+        /**
+         * Declares a parent resource for nested routes (single level)
+         */
+        parent(resource, param) {
             const parentConfig = {
-                namespace,
-                paramName: paramName ?? deriveParentParamName(namespace),
+                resource,
+                param: param ?? deriveParentParamName(resource),
             };
             return createBuilder({
                 ...state,
                 parentResource: parentConfig,
             });
         },
+        /**
+         * Declares multiple parent resources for deeply nested routes
+         */
+        parents(config) {
+            const parentConfigs = config.map((item) => ({
+                resource: item.resource,
+                param: item.param ?? deriveParentParamName(item.resource),
+            }));
+            return createBuilder({
+                ...state,
+                parentResources: parentConfigs,
+            });
+        },
         /**
          * Finalizes as a query procedure
          */
@@ -260,7 +287,10 @@ 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
         _precompiledExecutor: precompiledExecutor,
     };
@@ -275,36 +305,7 @@ function compileProcedure(type, handler, state) {
  * @internal
  */
 function createPrecompiledMiddlewareExecutor(middlewares, handler) {
-    // Pre-build the chain executor once
-    return async (input, ctx) => {
-        // Create mutable context copy for middleware extensions
-        const mutableCtx = ctx;
-        // Build the handler wrapper
-        const executeHandler = async () => {
-            const output = await handler({ input, ctx: mutableCtx });
-            return { output };
-        };
-        // Build chain from end to start (only done once per request, not per middleware)
-        let next = executeHandler;
-        for (let i = middlewares.length - 1; i >= 0; i--) {
-            const middleware = middlewares[i];
-            const currentNext = next;
-            next = async () => {
-                return middleware({
-                    input,
-                    ctx: mutableCtx,
-                    next: async (opts) => {
-                        if (opts?.ctx) {
-                            Object.assign(mutableCtx, opts.ctx);
-                        }
-                        return currentNext();
-                    },
-                });
-            };
-        }
-        const result = await next();
-        return result.output;
-    };
+    return createMiddlewareExecutor(middlewares, handler);
 }
 /**
  * Defines a collection of procedures under a namespace
@@ -502,31 +503,7 @@ export async function executeProcedure(procedure, rawInput, ctx) {
  * @internal
  */
 async function executeMiddlewareChainFallback(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;
+    return executeMiddlewareChain(middlewares, input, ctx, handler);
 }
 // ============================================================================
 // Type Utilities

package/dist/procedure/types.d.ts

@@ -249,16 +249,39 @@ export interface ProcedureBuilder<TInput = unknown, TOutput = unknown, TContext
      */
     rest(config: RestRouteOverride): ProcedureBuilder<TInput, TOutput, TContext>;
     /**
-     * Declares a parent resource for nested routes
+     * 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)
      *
      * When a procedure has a parent resource, the REST path will be nested
-     * under the parent: `/${parentNamespace}/:${parentParam}/${childNamespace}/:id`
+     * under the parent: `/${parentResource}/:${parentParam}/${childResource}/:id`
      *
      * The input schema should include the parent parameter (e.g., `postId`) for
      * proper type safety and runtime validation.
      *
-     * @param namespace - Parent resource namespace (e.g., 'posts', 'users')
-     * @param paramName - Optional custom parameter name (default: `${singularNamespace}Id`)
+     * @param resource - Parent resource name (e.g., 'posts', 'users')
+     * @param param - Optional custom parameter name (default: `${singularResource}Id`)
      * @returns Same builder (no type changes)
      *
      * @example
@@ -276,7 +299,38 @@ export interface ProcedureBuilder<TInput = unknown, TOutput = unknown, TContext
      *   .query(async ({ input }) => { ... });
      * ```
      */
-    parent(namespace: string, paramName?: string): ProcedureBuilder<TInput, TOutput, TContext>;
+    parent(resource: string, param?: string): ProcedureBuilder<TInput, TOutput, TContext>;
+    /**
+     * Declares multiple parent resources for deeply nested routes
+     *
+     * When a procedure has multiple parent resources, the REST path will be
+     * deeply nested: `/${parent1}/:${param1}/${parent2}/:${param2}/.../${child}/:id`
+     *
+     * The input schema should include ALL parent parameters for proper type safety.
+     *
+     * @param config - Array of parent resource configurations from outermost to innermost
+     * @returns Same builder (no type changes)
+     *
+     * @example
+     * ```typescript
+     * // Generates: GET /organizations/:orgId/projects/:projectId/tasks/:id
+     * const getTask = procedure()
+     *   .parents([
+     *     { resource: 'organizations', param: 'orgId' },
+     *     { resource: 'projects', param: 'projectId' },
+     *   ])
+     *   .input(z.object({
+     *     orgId: z.string(),
+     *     projectId: z.string(),
+     *     id: z.string()
+     *   }))
+     *   .query(async ({ input }) => { ... });
+     * ```
+     */
+    parents(config: Array<{
+        resource: string;
+        param?: string;
+    }>): ProcedureBuilder<TInput, TOutput, TContext>;
     /**
      * Finalizes the procedure as a query (read-only operation)
      *
@@ -333,8 +387,14 @@ export interface BuilderRuntimeState {
     guards: GuardLike<unknown>[];
     /** REST route override */
     restOverride?: RestRouteOverride;
-    /** Parent resource configuration for nested routes */
+    /** Parent resource configuration for nested routes (single level) */
     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/rest/adapter.d.ts

@@ -41,6 +41,35 @@ export interface RestAdapterOptions {
     prefix?: string;
     /** Custom error handler */
     onError?: (error: unknown, request: FastifyRequest, reply: FastifyReply) => void;
+    /**
+     * Generate flat shortcut routes alongside nested routes.
+     *
+     * When enabled, nested routes like `/organizations/:orgId/projects/:projectId/tasks/:id`
+     * will also generate a flat shortcut route like `/tasks/:id`.
+     *
+     * Note: Shortcuts only work for single-resource operations (GET, PUT, PATCH, DELETE with :id).
+     * Collection operations (list, create) require parent context and are NOT generated as shortcuts.
+     *
+     * @example
+     * ```typescript
+     * rest([tasks], { shortcuts: true })
+     * // Generates:
+     * // GET /organizations/:orgId/projects/:projectId/tasks/:id (nested)
+     * // GET /tasks/:id (shortcut)
+     * ```
+     *
+     * @default false
+     */
+    shortcuts?: boolean;
+    /**
+     * Enable warnings about deep nesting (3+ levels).
+     *
+     * When true (default), the router warns when nesting exceeds 3 levels.
+     * Set to false to silence these warnings.
+     *
+     * @default true
+     */
+    nestingWarnings?: boolean;
 }
 /**
  * Internal options used during route registration
@@ -53,6 +82,13 @@ interface InternalRegistrationOptions extends RestAdapterOptions {
      */
     _prefixHandledByFastify?: boolean;
 }
+/** Options for generating REST routes */
+export interface GenerateRestRoutesOptions {
+    /** Generate flat shortcut routes alongside nested routes */
+    shortcuts?: boolean;
+    /** Enable nesting depth warnings (default: true) */
+    nestingWarnings?: boolean;
+}
 /**
  * Generate REST routes from a procedure collection
  *
@@ -62,9 +98,10 @@ interface InternalRegistrationOptions extends RestAdapterOptions {
  * 3. Skipping if neither applies (tRPC-only procedure)
  *
  * @param collection - Procedure collection to generate routes from
+ * @param options - Optional route generation options
  * @returns Array of REST route definitions
  */
-export declare function generateRestRoutes(collection: ProcedureCollection): RestRoute[];
+export declare function generateRestRoutes(collection: ProcedureCollection, options?: GenerateRestRoutesOptions): RestRoute[];
 /**
  * Register REST routes from procedure collections onto a Fastify instance
  *

package/dist/rest/adapter.js

@@ -9,10 +9,9 @@
  */
 import { ConfigurationError } from '@veloxts/core';
 import { executeProcedure } from '../procedure/builder.js';
-import { buildNestedRestPath, buildRestPath, parseNamingConvention } from './naming.js';
-// ============================================================================
-// Route Generation
-// ============================================================================
+import { buildMultiLevelNestedPath, buildNestedRestPath, buildRestPath, calculateNestingDepth, parseNamingConvention, } from './naming.js';
+/** Default nesting depth threshold for warnings */
+const NESTING_DEPTH_WARNING_THRESHOLD = 3;
 /**
  * Generate REST routes from a procedure collection
  *
@@ -22,23 +21,90 @@ import { buildNestedRestPath, buildRestPath, parseNamingConvention } from './nam
  * 3. Skipping if neither applies (tRPC-only procedure)
  *
  * @param collection - Procedure collection to generate routes from
+ * @param options - Optional route generation options
  * @returns Array of REST route definitions
  */
-export function generateRestRoutes(collection) {
+export function generateRestRoutes(collection, options = {}) {
     const routes = [];
+    const { shortcuts = false, nestingWarnings = true } = options;
     for (const [name, procedure] of Object.entries(collection.procedures)) {
         const route = generateRouteForProcedure(name, procedure, collection.namespace);
         if (route) {
             routes.push(route);
+            // Check nesting depth and warn if too deep
+            if (nestingWarnings) {
+                const depth = calculateNestingDepth(procedure.parentResource, procedure.parentResources);
+                if (depth >= NESTING_DEPTH_WARNING_THRESHOLD) {
+                    console.warn(`⚠️  Resource '${collection.namespace}/${name}' has ${depth} levels of nesting. ` +
+                        `Consider using shortcuts: true or restructuring your API.`);
+                }
+            }
+            // Generate shortcut route if enabled and route is nested with ID parameter
+            if (shortcuts && isNestedRoute(procedure) && route.path.endsWith('/:id')) {
+                const shortcutRoute = generateFlatRoute(route, collection.namespace);
+                if (shortcutRoute) {
+                    routes.push(shortcutRoute);
+                }
+            }
         }
     }
     return routes;
 }
+/**
+ * Check if a procedure has parent resources (is nested)
+ */
+function isNestedRoute(procedure) {
+    return (procedure.parentResource !== undefined ||
+        (procedure.parentResources !== undefined && procedure.parentResources.length > 0));
+}
+/**
+ * Generate a shortcut route for a nested route
+ *
+ * Only generates shortcuts for single-resource operations (with :id).
+ * Collection operations require parent context and are not suitable for shortcuts.
+ */
+function generateFlatRoute(nestedRoute, namespace) {
+    // Only generate shortcuts for operations with :id (single resource)
+    if (!nestedRoute.path.endsWith('/:id')) {
+        return undefined;
+    }
+    // Build shortcut path: /{namespace}/:id
+    const shortcutPath = `/${namespace}/:id`;
+    return {
+        method: nestedRoute.method,
+        path: shortcutPath,
+        procedureName: `${nestedRoute.procedureName}Shortcut`,
+        procedure: nestedRoute.procedure,
+    };
+}
+/**
+ * Build the REST path for a procedure based on its nesting configuration
+ *
+ * Handles:
+ * - Flat routes: /users/:id
+ * - Single-level nested: /posts/:postId/comments/:id
+ * - Multi-level nested: /organizations/:orgId/projects/:projectId/tasks/:id
+ *
+ * @internal
+ */
+function buildProcedurePath(procedure, namespace, mapping) {
+    // Multi-level nesting takes precedence
+    if (procedure.parentResources && procedure.parentResources.length > 0) {
+        return buildMultiLevelNestedPath(procedure.parentResources, namespace, mapping);
+    }
+    // Single-level nesting
+    if (procedure.parentResource) {
+        return buildNestedRestPath(procedure.parentResource, namespace, mapping);
+    }
+    // Flat route
+    return buildRestPath(namespace, mapping);
+}
 /**
  * Generate a REST route for a single procedure
  *
- * Handles both flat routes (e.g., /users/:id) and nested routes
- * (e.g., /posts/:postId/comments/:id) when a parent resource is configured.
+ * Handles flat routes (e.g., /users/:id), single-level nested routes
+ * (e.g., /posts/:postId/comments/:id), and multi-level nested routes
+ * (e.g., /organizations/:orgId/projects/:projectId/tasks/:id).
  *
  * @internal
  */
@@ -60,11 +126,8 @@ function generateRouteForProcedure(name, procedure, namespace) {
         // Partial override - try to fill in missing parts from convention
         const convention = parseNamingConvention(name, procedure.type);
         if (convention) {
-            // Build path based on whether there's a parent resource
-            const path = override.path ??
-                (procedure.parentResource
-                    ? buildNestedRestPath(procedure.parentResource, namespace, convention)
-                    : buildRestPath(namespace, convention));
+            // Build path based on nesting configuration
+            const path = override.path ?? buildProcedurePath(procedure, namespace, convention);
             return {
                 method: override.method ?? convention.method,
                 path,
@@ -78,10 +141,8 @@ function generateRouteForProcedure(name, procedure, namespace) {
     // Try to infer from naming convention
     const mapping = parseNamingConvention(name, procedure.type);
     if (mapping) {
-        // Build path based on whether there's a parent resource
-        const path = procedure.parentResource
-            ? buildNestedRestPath(procedure.parentResource, namespace, mapping)
-            : buildRestPath(namespace, mapping);
+        // Build path based on nesting configuration
+        const path = buildProcedurePath(procedure, namespace, mapping);
         return {
             method: mapping.method,
             path,
@@ -143,32 +204,34 @@ function isPlainObject(value) {
  * Gather input data from the request based on HTTP method
  *
  * - GET: Merge params and query
- * - POST: Use body, but merge params for nested routes (parent ID in URL)
+ * - POST: Use body, but merge params for nested routes (parent IDs in URL)
  * - PUT/PATCH: Merge params (for ID) and body (for data)
  * - DELETE: Merge params and query (no body per REST conventions)
  *
- * For nested routes (e.g., /posts/:postId/comments), the parent param
- * is extracted from the URL and merged with the body/query as appropriate.
+ * For nested routes (e.g., /posts/:postId/comments or
+ * /organizations/:orgId/projects/:projectId/tasks), all parent params
+ * are extracted from the URL and merged with the body/query as appropriate.
  */
 function gatherInput(request, route) {
     const params = isPlainObject(request.params) ? request.params : {};
     const query = isPlainObject(request.query) ? request.query : {};
     const body = isPlainObject(request.body) ? request.body : {};
-    // Check if this is a nested route (has parent resource)
-    const hasParentResource = route.procedure.parentResource !== undefined;
+    // Check if this is a nested route (has single parent or multiple parents)
+    const hasParentResource = route.procedure.parentResource !== undefined ||
+        (route.procedure.parentResources !== undefined && route.procedure.parentResources.length > 0);
     switch (route.method) {
         case 'GET':
-            // GET: params (for :id and parent params) + query (for filters/pagination)
+            // GET: params (for :id and all parent params) + query (for filters/pagination)
             return { ...params, ...query };
         case 'DELETE':
-            // DELETE: params (for :id and parent params) + query (for options), no body per REST conventions
+            // DELETE: params (for :id and all parent params) + query (for options), no body per REST conventions
             return { ...params, ...query };
         case 'PUT':
         case 'PATCH':
-            // PUT/PATCH: params (for :id and parent params) + body (for data)
+            // PUT/PATCH: params (for :id and all parent params) + body (for data)
             return { ...params, ...body };
         case 'POST':
-            // POST: For nested routes, merge params (for parent ID) with body
+            // POST: For nested routes, merge params (for all parent IDs) with body
             // For flat routes, use body only (no ID in params for creates)
             if (hasParentResource) {
                 return { ...params, ...body };
@@ -244,9 +307,13 @@ function getContextFromRequest(request) {
  * ```
  */
 export function registerRestRoutes(server, collections, options = {}) {
-    const { prefix = '/api', _prefixHandledByFastify = false } = options;
+    const { prefix = '/api', _prefixHandledByFastify = false, shortcuts = false, nestingWarnings = true, } = options;
+    const routeGenOptions = {
+        shortcuts,
+        nestingWarnings,
+    };
     for (const collection of collections) {
-        const routes = generateRestRoutes(collection);
+        const routes = generateRestRoutes(collection, routeGenOptions);
         for (const route of routes) {
             // When used with server.register(), Fastify handles the prefix automatically.
             // When used in legacy mode, we prepend the prefix manually.

package/dist/rest/index.d.ts

@@ -3,9 +3,9 @@
  *
  * @module rest
  */
-export type { RestAdapterOptions, RestPlugin, RestRoute } from './adapter.js';
+export type { GenerateRestRoutesOptions, RestAdapterOptions, RestPlugin, RestRoute, } from './adapter.js';
 export { generateRestRoutes, getRouteSummary, registerRestRoutes, rest, } from './adapter.js';
 export type { RestMapping } from './naming.js';
-export { buildNestedRestPath, buildRestPath, followsNamingConvention, inferResourceName, parseNamingConvention, } from './naming.js';
+export { buildMultiLevelNestedPath, buildNestedRestPath, buildRestPath, calculateNestingDepth, followsNamingConvention, inferResourceName, parseNamingConvention, } from './naming.js';
 export type { ExtractRoutesType, RouteEntry, RouteMap } from './routes.js';
 export { extractRoutes } from './routes.js';

package/dist/rest/index.js

@@ -4,5 +4,5 @@
  * @module rest
  */
 export { generateRestRoutes, getRouteSummary, registerRestRoutes, rest, } from './adapter.js';
-export { buildNestedRestPath, buildRestPath, followsNamingConvention, inferResourceName, parseNamingConvention, } from './naming.js';
+export { buildMultiLevelNestedPath, buildNestedRestPath, buildRestPath, calculateNestingDepth, followsNamingConvention, inferResourceName, parseNamingConvention, } from './naming.js';
 export { extractRoutes } from './routes.js';