@veloxts/router 0.6.84 → 0.6.85

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';

package/dist/rest/naming.d.ts

@@ -59,7 +59,7 @@ export declare function parseNamingConvention(name: string, type: ProcedureType)
  */
 export declare function buildRestPath(namespace: string, mapping: RestMapping): string;
 /**
- * Build a nested REST path with parent resource prefix
+ * Build a nested REST path with parent resource prefix (single level)
  *
  * Creates paths like `/posts/:postId/comments/:id` for nested resources.
  *
@@ -70,7 +70,7 @@ export declare function buildRestPath(namespace: string, mapping: RestMapping):
  *
  * @example
  * ```typescript
- * const parent = { namespace: 'posts', paramName: 'postId' };
+ * const parent = { resource: 'posts', param: 'postId' };
  *
  * buildNestedRestPath(parent, 'comments', { method: 'GET', path: '/:id', hasIdParam: true })
  * // Returns: '/posts/:postId/comments/:id'
@@ -83,6 +83,42 @@ export declare function buildRestPath(namespace: string, mapping: RestMapping):
  * ```
  */
 export declare function buildNestedRestPath(parentResource: ParentResourceConfig, childNamespace: string, mapping: RestMapping): string;
+/**
+ * Build a deeply nested REST path with multiple parent resources
+ *
+ * Creates paths like `/organizations/:orgId/projects/:projectId/tasks/:id`
+ * for deeply nested resources.
+ *
+ * @param parentResources - Array of parent resource configurations (outermost to innermost)
+ * @param childNamespace - Child resource namespace (e.g., 'tasks')
+ * @param mapping - REST mapping from parseNamingConvention
+ * @returns Full deeply nested path
+ *
+ * @example
+ * ```typescript
+ * const parents = [
+ *   { resource: 'organizations', param: 'orgId' },
+ *   { resource: 'projects', param: 'projectId' },
+ * ];
+ *
+ * buildMultiLevelNestedPath(parents, 'tasks', { method: 'GET', path: '/:id', hasIdParam: true })
+ * // Returns: '/organizations/:orgId/projects/:projectId/tasks/:id'
+ *
+ * buildMultiLevelNestedPath(parents, 'tasks', { method: 'GET', path: '/', hasIdParam: false })
+ * // Returns: '/organizations/:orgId/projects/:projectId/tasks'
+ * ```
+ */
+export declare function buildMultiLevelNestedPath(parentResources: readonly ParentResourceConfig[], childNamespace: string, mapping: RestMapping): string;
+/**
+ * Calculate the nesting depth of a route
+ *
+ * Returns the number of parent levels plus 1 for the resource itself.
+ *
+ * @param parentResource - Single parent resource (optional)
+ * @param parentResources - Multiple parent resources (optional)
+ * @returns The total nesting depth (1 = flat, 2 = one parent, 3+ = deeply nested)
+ */
+export declare function calculateNestingDepth(parentResource?: ParentResourceConfig, parentResources?: readonly ParentResourceConfig[]): number;
 /**
  * Infer the resource name from a procedure name
  *

package/dist/rest/naming.js

@@ -140,6 +140,16 @@ export function parseNamingConvention(name, type) {
     // No convention matched
     return undefined;
 }
+/**
+ * Append the mapping suffix to a base path
+ *
+ * @param basePath - The base path (e.g., '/users', '/posts/:postId/comments')
+ * @param mapping - REST mapping containing the path suffix
+ * @returns The complete path with suffix appended (if not just '/')
+ */
+function appendMappingSuffix(basePath, mapping) {
+    return mapping.path === '/' ? basePath : `${basePath}${mapping.path}`;
+}
 /**
  * Build the full REST path from namespace and mapping
  *
@@ -157,16 +167,10 @@ export function parseNamingConvention(name, type) {
  * ```
  */
 export function buildRestPath(namespace, mapping) {
-    const basePath = `/${namespace}`;
-    // If path is just '/', return the base path without trailing slash
-    if (mapping.path === '/') {
-        return basePath;
-    }
-    // Otherwise append the path (e.g., '/:id')
-    return `${basePath}${mapping.path}`;
+    return appendMappingSuffix(`/${namespace}`, mapping);
 }
 /**
- * Build a nested REST path with parent resource prefix
+ * Build a nested REST path with parent resource prefix (single level)
  *
  * Creates paths like `/posts/:postId/comments/:id` for nested resources.
  *
@@ -177,7 +181,7 @@ export function buildRestPath(namespace, mapping) {
  *
  * @example
  * ```typescript
- * const parent = { namespace: 'posts', paramName: 'postId' };
+ * const parent = { resource: 'posts', param: 'postId' };
  *
  * buildNestedRestPath(parent, 'comments', { method: 'GET', path: '/:id', hasIdParam: true })
  * // Returns: '/posts/:postId/comments/:id'
@@ -190,16 +194,59 @@ export function buildRestPath(namespace, mapping) {
  * ```
  */
 export function buildNestedRestPath(parentResource, childNamespace, mapping) {
-    // Build parent path segment: /{parentNamespace}/:{parentParamName}
-    const parentPath = `/${parentResource.namespace}/:${parentResource.paramName}`;
-    // Build child path segment
-    const childBasePath = `/${childNamespace}`;
-    // If mapping path is just '/', don't add extra suffix
-    if (mapping.path === '/') {
-        return `${parentPath}${childBasePath}`;
+    const parentPath = `/${parentResource.resource}/:${parentResource.param}`;
+    const basePath = `${parentPath}/${childNamespace}`;
+    return appendMappingSuffix(basePath, mapping);
+}
+/**
+ * Build a deeply nested REST path with multiple parent resources
+ *
+ * Creates paths like `/organizations/:orgId/projects/:projectId/tasks/:id`
+ * for deeply nested resources.
+ *
+ * @param parentResources - Array of parent resource configurations (outermost to innermost)
+ * @param childNamespace - Child resource namespace (e.g., 'tasks')
+ * @param mapping - REST mapping from parseNamingConvention
+ * @returns Full deeply nested path
+ *
+ * @example
+ * ```typescript
+ * const parents = [
+ *   { resource: 'organizations', param: 'orgId' },
+ *   { resource: 'projects', param: 'projectId' },
+ * ];
+ *
+ * buildMultiLevelNestedPath(parents, 'tasks', { method: 'GET', path: '/:id', hasIdParam: true })
+ * // Returns: '/organizations/:orgId/projects/:projectId/tasks/:id'
+ *
+ * buildMultiLevelNestedPath(parents, 'tasks', { method: 'GET', path: '/', hasIdParam: false })
+ * // Returns: '/organizations/:orgId/projects/:projectId/tasks'
+ * ```
+ */
+export function buildMultiLevelNestedPath(parentResources, childNamespace, mapping) {
+    const parentSegments = parentResources
+        .map((parent) => `/${parent.resource}/:${parent.param}`)
+        .join('');
+    const basePath = `${parentSegments}/${childNamespace}`;
+    return appendMappingSuffix(basePath, mapping);
+}
+/**
+ * Calculate the nesting depth of a route
+ *
+ * Returns the number of parent levels plus 1 for the resource itself.
+ *
+ * @param parentResource - Single parent resource (optional)
+ * @param parentResources - Multiple parent resources (optional)
+ * @returns The total nesting depth (1 = flat, 2 = one parent, 3+ = deeply nested)
+ */
+export function calculateNestingDepth(parentResource, parentResources) {
+    if (parentResources && parentResources.length > 0) {
+        return parentResources.length + 1;
+    }
+    if (parentResource) {
+        return 2;
     }
-    // Otherwise append the path (e.g., '/:id')
-    return `${parentPath}${childBasePath}${mapping.path}`;
+    return 1;
 }
 /**
  * Infer the resource name from a procedure name

package/dist/rpc.d.ts

@@ -0,0 +1,144 @@
+/**
+ * RPC helper for type-safe tRPC registration
+ *
+ * Provides a symmetric API to `rest()` for registering tRPC endpoints
+ * with full type preservation for client inference.
+ *
+ * @module rpc
+ */
+import { type VeloxApp } from '@veloxts/core';
+import type { FastifyInstance } from 'fastify';
+import { type AnyRouter, type InferRouterFromCollections } from './trpc/index.js';
+import type { ProcedureCollection } from './types.js';
+/**
+ * Options for RPC registration
+ */
+export interface RpcOptions {
+    /**
+     * tRPC endpoint prefix
+     *
+     * @default '/trpc'
+     */
+    prefix?: string;
+}
+/**
+ * Result of rpc() for type-safe router access
+ *
+ * Contains both the typed router (for type export) and an async
+ * registration function (for registering with Fastify).
+ */
+export interface RpcResult<T extends readonly ProcedureCollection[]> {
+    /**
+     * The typed tRPC router
+     *
+     * Use `typeof router` to export the AppRouter type for clients.
+     *
+     * @example
+     * ```typescript
+     * const { router } = rpc([userProcedures, postProcedures] as const);
+     * export type AppRouter = typeof router;
+     * ```
+     */
+    readonly router: AnyRouter & InferRouterFromCollections<T>;
+    /**
+     * Register the tRPC routes with a Fastify instance
+     *
+     * This is an async function that registers the tRPC plugin.
+     *
+     * @param server - Fastify instance or VeloxApp
+     *
+     * @example
+     * ```typescript
+     * const { register } = rpc([userProcedures] as const);
+     * await register(app.server);
+     * ```
+     */
+    readonly register: (server: FastifyInstance) => Promise<void>;
+}
+/**
+ * Create a type-safe tRPC router from procedure collections
+ *
+ * This is the RPC equivalent of `rest()`. It returns a typed router
+ * and a registration function, enabling proper type inference for
+ * client-side usage.
+ *
+ * **IMPORTANT**: Use `as const` on the collections array to preserve
+ * literal types for full type inference.
+ *
+ * @param collections - Array of procedure collections (use `as const`)
+ * @param options - Optional RPC configuration
+ * @returns RpcResult with typed router and register function
+ *
+ * @example Basic usage with VeloxApp
+ * ```typescript
+ * import { veloxApp } from '@veloxts/core';
+ * import { rpc } from '@veloxts/router';
+ *
+ * const app = await veloxApp({ port: 3030 });
+ *
+ * const { router, register } = rpc([
+ *   userProcedures,
+ *   postProcedures,
+ * ] as const);
+ *
+ * // Register tRPC routes
+ * await register(app.server);
+ *
+ * // Export type for clients - fully typed!
+ * export type AppRouter = typeof router;
+ *
+ * await app.start();
+ * ```
+ *
+ * @example With custom prefix
+ * ```typescript
+ * const { router, register } = rpc([userProcedures] as const, {
+ *   prefix: '/api/trpc',
+ * });
+ *
+ * await register(app.server);
+ * export type AppRouter = typeof router;
+ * ```
+ *
+ * @example Combined with REST
+ * ```typescript
+ * // Serve same procedures via both REST and tRPC
+ * const collections = [userProcedures, postProcedures] as const;
+ *
+ * // REST endpoints at /api/*
+ * app.routes(rest([...collections], { prefix: '/api' }));
+ *
+ * // tRPC endpoints at /trpc/*
+ * const { router, register } = rpc(collections);
+ * await register(app.server);
+ *
+ * export type AppRouter = typeof router;
+ * ```
+ */
+export declare function rpc<const T extends readonly ProcedureCollection[]>(collections: T, options?: RpcOptions): RpcResult<T>;
+/**
+ * Register tRPC routes and return the typed router
+ *
+ * This is a convenience function that combines router creation and
+ * registration in a single async call. Use this when you don't need
+ * to separate router creation from registration.
+ *
+ * **IMPORTANT**: Use `as const` on the collections array to preserve
+ * literal types for full type inference.
+ *
+ * @param app - VeloxApp instance
+ * @param collections - Array of procedure collections (use `as const`)
+ * @param options - Optional RPC configuration
+ * @returns The typed tRPC router
+ *
+ * @example
+ * ```typescript
+ * const router = await registerRpc(app, [
+ *   userProcedures,
+ *   postProcedures,
+ * ] as const);
+ *
+ * export type AppRouter = typeof router;
+ * ```
+ */
+export declare function registerRpc<const T extends readonly ProcedureCollection[]>(app: VeloxApp, collections: T, options?: RpcOptions): Promise<AnyRouter & InferRouterFromCollections<T>>;

package/dist/rpc.js

@@ -0,0 +1,127 @@
+/**
+ * RPC helper for type-safe tRPC registration
+ *
+ * Provides a symmetric API to `rest()` for registering tRPC endpoints
+ * with full type preservation for client inference.
+ *
+ * @module rpc
+ */
+import { fail } from '@veloxts/core';
+import { appRouter, registerTRPCPlugin, trpc, } from './trpc/index.js';
+// ============================================================================
+// Main Function
+// ============================================================================
+/**
+ * Create a type-safe tRPC router from procedure collections
+ *
+ * This is the RPC equivalent of `rest()`. It returns a typed router
+ * and a registration function, enabling proper type inference for
+ * client-side usage.
+ *
+ * **IMPORTANT**: Use `as const` on the collections array to preserve
+ * literal types for full type inference.
+ *
+ * @param collections - Array of procedure collections (use `as const`)
+ * @param options - Optional RPC configuration
+ * @returns RpcResult with typed router and register function
+ *
+ * @example Basic usage with VeloxApp
+ * ```typescript
+ * import { veloxApp } from '@veloxts/core';
+ * import { rpc } from '@veloxts/router';
+ *
+ * const app = await veloxApp({ port: 3030 });
+ *
+ * const { router, register } = rpc([
+ *   userProcedures,
+ *   postProcedures,
+ * ] as const);
+ *
+ * // Register tRPC routes
+ * await register(app.server);
+ *
+ * // Export type for clients - fully typed!
+ * export type AppRouter = typeof router;
+ *
+ * await app.start();
+ * ```
+ *
+ * @example With custom prefix
+ * ```typescript
+ * const { router, register } = rpc([userProcedures] as const, {
+ *   prefix: '/api/trpc',
+ * });
+ *
+ * await register(app.server);
+ * export type AppRouter = typeof router;
+ * ```
+ *
+ * @example Combined with REST
+ * ```typescript
+ * // Serve same procedures via both REST and tRPC
+ * const collections = [userProcedures, postProcedures] as const;
+ *
+ * // REST endpoints at /api/*
+ * app.routes(rest([...collections], { prefix: '/api' }));
+ *
+ * // tRPC endpoints at /trpc/*
+ * const { router, register } = rpc(collections);
+ * await register(app.server);
+ *
+ * export type AppRouter = typeof router;
+ * ```
+ */
+export function rpc(collections, options = {}) {
+    const { prefix = '/trpc' } = options;
+    // Validate inputs
+    if (collections.length === 0) {
+        throw fail('VELOX-2006');
+    }
+    // Create the typed router immediately
+    const t = trpc();
+    const router = appRouter(t, collections);
+    // Create the registration function
+    const register = async (server) => {
+        await registerTRPCPlugin(server, {
+            prefix,
+            router,
+        });
+    };
+    return {
+        router,
+        register,
+    };
+}
+// ============================================================================
+// Async Helper (Alternative API)
+// ============================================================================
+/**
+ * Register tRPC routes and return the typed router
+ *
+ * This is a convenience function that combines router creation and
+ * registration in a single async call. Use this when you don't need
+ * to separate router creation from registration.
+ *
+ * **IMPORTANT**: Use `as const` on the collections array to preserve
+ * literal types for full type inference.
+ *
+ * @param app - VeloxApp instance
+ * @param collections - Array of procedure collections (use `as const`)
+ * @param options - Optional RPC configuration
+ * @returns The typed tRPC router
+ *
+ * @example
+ * ```typescript
+ * const router = await registerRpc(app, [
+ *   userProcedures,
+ *   postProcedures,
+ * ] as const);
+ *
+ * export type AppRouter = typeof router;
+ * ```
+ */
+export async function registerRpc(app, collections, options = {}) {
+    const { router, register } = rpc(collections, options);
+    await register(app.server);
+    return router;
+}