@veloxts/router 0.6.83 → 0.6.85

package/dist/trpc/adapter.d.ts

@@ -6,7 +6,7 @@
  *
  * @module trpc/adapter
  */
-import type { AnyRouter as TRPCAnyRouter } from '@trpc/server';
+import type { AnyRouter as TRPCAnyRouter, TRPCMutationProcedure, TRPCQueryProcedure } from '@trpc/server';
 import { TRPCError } from '@trpc/server';
 import type { BaseContext } from '@veloxts/core';
 import type { FastifyInstance } from 'fastify';
@@ -17,7 +17,83 @@ import type { FastifyInstance } from 'fastify';
  * which helps avoid TypeScript compilation memory issues with tRPC v11.7+.
  */
 export type AnyRouter = TRPCAnyRouter;
-import type { ProcedureCollection } from '../types.js';
+import type { CompiledProcedure, ProcedureCollection, ProcedureRecord } from '../types.js';
+/**
+ * Maps a VeloxTS CompiledProcedure to the corresponding tRPC procedure type
+ *
+ * This preserves the input/output types through the type mapping, enabling
+ * proper type inference when using the router on the client.
+ *
+ * Note: The `meta` field is required by tRPC's BuiltProcedureDef interface.
+ * We use `unknown` since VeloxTS doesn't use procedure-level metadata.
+ */
+export type MapProcedureToTRPC<T extends CompiledProcedure> = T extends CompiledProcedure<infer TInput, infer TOutput, BaseContext, 'query'> ? TRPCQueryProcedure<{
+    input: TInput;
+    output: TOutput;
+    meta: unknown;
+}> : T extends CompiledProcedure<infer TInput, infer TOutput, BaseContext, 'mutation'> ? TRPCMutationProcedure<{
+    input: TInput;
+    output: TOutput;
+    meta: unknown;
+}> : never;
+/**
+ * Maps a ProcedureRecord to a tRPC router record with proper types
+ *
+ * This preserves each procedure's input/output types through the mapping.
+ */
+export type MapProcedureRecordToTRPC<T extends ProcedureRecord> = {
+    [K in keyof T]: MapProcedureToTRPC<T[K]>;
+};
+/**
+ * Extracts the namespace from a ProcedureCollection
+ */
+export type ExtractNamespace<T> = T extends ProcedureCollection<infer N, ProcedureRecord> ? N : never;
+/**
+ * Extracts the procedures record from a ProcedureCollection
+ */
+export type ExtractProcedures<T> = T extends ProcedureCollection<string, infer P> ? P : never;
+/**
+ * Maps a tuple of ProcedureCollections to a tRPC router record
+ *
+ * This creates a properly typed object where each key is the namespace
+ * and each value is the mapped procedure record.
+ *
+ * @example
+ * ```typescript
+ * type Collections = [
+ *   ProcedureCollection<'users', { getUser: CompiledProcedure<...> }>,
+ *   ProcedureCollection<'posts', { listPosts: CompiledProcedure<...> }>
+ * ];
+ *
+ * type Result = CollectionsToRouterRecord<Collections>;
+ * // Result = {
+ * //   users: { getUser: TRPCQueryProcedure<...> },
+ * //   posts: { listPosts: TRPCQueryProcedure<...> }
+ * // }
+ * ```
+ */
+export type CollectionsToRouterRecord<T extends readonly ProcedureCollection[]> = T extends readonly [] ? object : T extends readonly [infer First extends ProcedureCollection, ...infer Rest] ? Rest extends readonly ProcedureCollection[] ? {
+    [K in ExtractNamespace<First>]: MapProcedureRecordToTRPC<ExtractProcedures<First>>;
+} & CollectionsToRouterRecord<Rest> : {
+    [K in ExtractNamespace<First>]: MapProcedureRecordToTRPC<ExtractProcedures<First>>;
+} : object;
+/**
+ * Infers the complete router type from procedure collections
+ *
+ * This is the main type that should be used for `export type AppRouter = ...`
+ * to ensure full type preservation for the tRPC client.
+ *
+ * @example
+ * ```typescript
+ * const collections = [userProcedures, postProcedures] as const;
+ * const router = await rpc(app, collections);
+ * export type AppRouter = InferRouterFromCollections<typeof collections>;
+ *
+ * // Client usage:
+ * // client.users.getUser({ id: '123' }) // Fully typed!
+ * ```
+ */
+export type InferRouterFromCollections<T extends readonly ProcedureCollection[]> = CollectionsToRouterRecord<T>;
 declare const baseTRPC: import("@trpc/server").TRPCRootObject<BaseContext, object, import("@trpc/server").TRPCRuntimeConfigOptions<BaseContext, object>, {
     ctx: BaseContext;
     meta: object;
@@ -73,10 +149,11 @@ export declare function buildTRPCRouter(t: TRPCInstance<BaseContext>, collection
  * Create a namespaced app router from multiple procedure collections
  *
  * Each collection becomes a nested router under its namespace.
+ * Use `as const` on the collections array to preserve literal types.
  *
  * @param t - tRPC instance
- * @param collections - Array of procedure collections
- * @returns Merged app router
+ * @param collections - Array of procedure collections (use `as const` for best type inference)
+ * @returns Merged app router with preserved types
  *
  * @example
  * ```typescript
@@ -84,21 +161,62 @@ export declare function buildTRPCRouter(t: TRPCInstance<BaseContext>, collection
  * const router = appRouter(t, [
  *   userProcedures,    // namespace: 'users'
  *   postProcedures,    // namespace: 'posts'
- * ]);
+ * ] as const);
  *
  * // Usage:
  * // router.users.getUser({ id: '123' })
  * // router.posts.listPosts({ page: 1 })
  *
- * // Export type for client
+ * // Export type for client - fully typed!
  * export type AppRouter = typeof router;
  * ```
  */
-export declare function appRouter(t: TRPCInstance<BaseContext>, collections: ProcedureCollection[]): AnyRouter;
+export declare function appRouter<const T extends readonly ProcedureCollection[]>(t: TRPCInstance<BaseContext>, collections: T): AnyRouter & InferRouterFromCollections<T>;
 /**
- * Helper type to infer the AppRouter type
+ * Helper type to infer the AppRouter type from procedure collections
+ *
+ * @deprecated Use `InferRouterFromCollections<T>` instead for better type inference.
+ * This type alias is kept for backward compatibility.
  */
-export type InferAppRouter = AnyRouter;
+export type InferAppRouter<T extends readonly ProcedureCollection[] = readonly ProcedureCollection[]> = InferRouterFromCollections<T>;
+/**
+ * Converts a VeloxTS router to a tRPC-compatible type for `@trpc/react-query`.
+ *
+ * @example
+ * ```typescript
+ * import { createTRPCReact } from '@trpc/react-query';
+ * import type { TRPCRouter } from '@veloxts/router';
+ * import type { AppRouter } from '../api';
+ *
+ * export const trpc = createTRPCReact<TRPCRouter<AppRouter>>();
+ * ```
+ *
+ * @see {@link InferRouterFromCollections} for transforming collections array types
+ */
+export type TRPCRouter<TRouter> = TRouter extends Record<string, ProcedureCollection<string, ProcedureRecord>> ? TRPCRouterBase & {
+    [K in keyof TRouter]: TRouter[K] extends ProcedureCollection<string, infer P extends ProcedureRecord> ? MapProcedureRecordToTRPC<P> : never;
+} : never;
+/**
+ * @deprecated Use `TRPCRouter` instead. Will be removed in v1.0.
+ */
+export type AsTRPCRouter<TRouter> = TRPCRouter<TRouter>;
+/**
+ * tRPC router structural requirements for type compatibility.
+ * @internal
+ */
+type TRPCRouterBase = {
+    _def: {
+        _config: {
+            $types: {
+                ctx: BaseContext;
+                meta: unknown;
+            };
+        };
+        record: Record<string, unknown>;
+        procedures: Record<string, unknown>;
+    };
+    createCaller: (ctx: unknown) => unknown;
+};
 /**
  * Create a tRPC context factory for Fastify
  *
@@ -126,6 +244,17 @@ export declare function createTRPCContextFactory(): ({ req }: {
         context?: BaseContext;
     };
 }) => BaseContext;
+/**
+ * Cause structure for VeloxTS errors converted to tRPC errors
+ */
+export interface VeloxTRPCCause {
+    /** Discriminator for VeloxTS errors */
+    readonly source: 'velox';
+    /** VeloxTS error code */
+    readonly code?: string;
+    /** Guard name (only present for GuardError) */
+    readonly guardName?: string;
+}
 /**
  * Convert a VeloxTS error to a tRPC error
  *
@@ -147,7 +276,7 @@ export declare function veloxErrorToTRPCError(error: Error & {
  * using veloxErrorToTRPCError().
  */
 export declare function isVeloxTRPCError(error: TRPCError): error is TRPCError & {
-    cause: string;
+    cause: VeloxTRPCCause;
 };
 /**
  * Options for tRPC plugin registration

package/dist/trpc/adapter.js

@@ -8,6 +8,7 @@
  */
 import { initTRPC, TRPCError } from '@trpc/server';
 import { isGuardError } from '../errors.js';
+import { executeMiddlewareChain } from '../middleware/chain.js';
 // ============================================================================
 // tRPC Initialization
 // ============================================================================
@@ -74,33 +75,23 @@ export function buildTRPCRouter(t, collection) {
  * @internal
  */
 function buildTRPCProcedure(t, procedure) {
-    // Start with base procedure builder
-    const baseProcedure = t.procedure;
-    // Build the procedure chain based on configuration
-    if (procedure.inputSchema && procedure.outputSchema) {
-        // Both input and output schemas
-        const withInput = baseProcedure.input(procedure.inputSchema);
-        const withOutput = withInput.output(procedure.outputSchema);
-        const handler = createHandler(procedure);
-        return procedure.type === 'query' ? withOutput.query(handler) : withOutput.mutation(handler);
-    }
+    // Build the procedure chain incrementally
+    // biome-ignore lint/suspicious/noExplicitAny: tRPC procedure builder has complex types that vary by chain state
+    let builder = t.procedure;
+    // Add input schema if present
     if (procedure.inputSchema) {
-        // Only input schema
-        const withInput = baseProcedure.input(procedure.inputSchema);
-        const handler = createHandler(procedure);
-        return procedure.type === 'query' ? withInput.query(handler) : withInput.mutation(handler);
+        builder = builder.input(procedure.inputSchema);
     }
+    // Add output schema if present
     if (procedure.outputSchema) {
-        // Only output schema
-        const withOutput = baseProcedure.output(procedure.outputSchema);
-        const handler = createNoInputHandler(procedure);
-        return procedure.type === 'query' ? withOutput.query(handler) : withOutput.mutation(handler);
+        builder = builder.output(procedure.outputSchema);
     }
-    // No schemas - use base procedure
-    const handler = createNoInputHandler(procedure);
-    return procedure.type === 'query'
-        ? baseProcedure.query(handler)
-        : baseProcedure.mutation(handler);
+    // Select handler based on whether input is expected
+    const handler = procedure.inputSchema
+        ? createHandler(procedure)
+        : createNoInputHandler(procedure);
+    // Finalize as query or mutation
+    return procedure.type === 'query' ? builder.query(handler) : builder.mutation(handler);
 }
 /**
  * Create a handler function for a procedure with input
@@ -141,31 +132,7 @@ function createNoInputHandler(procedure) {
  * @internal
  */
 async function executeWithMiddleware(procedure, input, ctx) {
-    // Build middleware chain from end to start
-    let next = async () => {
-        const output = await procedure.handler({ input, ctx });
-        return { output };
-    };
-    // Wrap each middleware from last to first
-    for (let i = procedure.middlewares.length - 1; i >= 0; i--) {
-        const middleware = procedure.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(procedure.middlewares, input, ctx, async () => procedure.handler({ input, ctx }));
 }
 // ============================================================================
 // App Router Creation
@@ -174,10 +141,11 @@ async function executeWithMiddleware(procedure, input, ctx) {
  * Create a namespaced app router from multiple procedure collections
  *
  * Each collection becomes a nested router under its namespace.
+ * Use `as const` on the collections array to preserve literal types.
  *
  * @param t - tRPC instance
- * @param collections - Array of procedure collections
- * @returns Merged app router
+ * @param collections - Array of procedure collections (use `as const` for best type inference)
+ * @returns Merged app router with preserved types
  *
  * @example
  * ```typescript
@@ -185,13 +153,13 @@ async function executeWithMiddleware(procedure, input, ctx) {
  * const router = appRouter(t, [
  *   userProcedures,    // namespace: 'users'
  *   postProcedures,    // namespace: 'posts'
- * ]);
+ * ] as const);
  *
  * // Usage:
  * // router.users.getUser({ id: '123' })
  * // router.posts.listPosts({ page: 1 })
  *
- * // Export type for client
+ * // Export type for client - fully typed!
  * export type AppRouter = typeof router;
  * ```
  */
@@ -239,9 +207,6 @@ export function createTRPCContextFactory() {
         return req.context;
     };
 }
-// ============================================================================
-// Error Utilities
-// ============================================================================
 /**
  * Convert a VeloxTS error to a tRPC error
  *
@@ -268,19 +233,25 @@ export function veloxErrorToTRPCError(error, defaultCode = 'INTERNAL_SERVER_ERRO
     const trpcCode = error.statusCode ? (statusToTRPC[error.statusCode] ?? defaultCode) : defaultCode;
     // Handle GuardError specifically to preserve guard metadata
     if (isGuardError(error)) {
+        const cause = {
+            source: 'velox',
+            code: error.code,
+            guardName: error.guardName,
+        };
         return new TRPCError({
             code: trpcCode,
             message: error.message,
-            cause: {
-                code: error.code,
-                guardName: error.guardName,
-            },
+            cause,
         });
     }
+    const cause = {
+        source: 'velox',
+        code: error.code,
+    };
     return new TRPCError({
         code: trpcCode,
         message: error.message,
-        cause: error.code,
+        cause,
     });
 }
 /**
@@ -290,7 +261,8 @@ export function veloxErrorToTRPCError(error, defaultCode = 'INTERNAL_SERVER_ERRO
  * using veloxErrorToTRPCError().
  */
 export function isVeloxTRPCError(error) {
-    return typeof error.cause === 'string';
+    const cause = error.cause;
+    return (cause != null && typeof cause === 'object' && 'source' in cause && cause.source === 'velox');
 }
 /**
  * Register tRPC plugin with Fastify server

package/dist/trpc/index.d.ts

@@ -3,5 +3,7 @@
  *
  * @module trpc
  */
-export type { AnyRouter, InferAppRouter, TRPCInstance, TRPCPluginOptions } from './adapter.js';
+export type { AnyRouter, 
+/** @deprecated Use `TRPCRouter` instead */
+AsTRPCRouter, CollectionsToRouterRecord, ExtractNamespace, ExtractProcedures, InferAppRouter, InferRouterFromCollections, MapProcedureRecordToTRPC, MapProcedureToTRPC, TRPCInstance, TRPCPluginOptions, TRPCRouter, } from './adapter.js';
 export { appRouter, buildTRPCRouter, createTRPCContextFactory, isVeloxTRPCError, registerTRPCPlugin, trpc, veloxErrorToTRPCError, } from './adapter.js';

package/dist/types.d.ts

@@ -193,7 +193,7 @@ export interface RestRouteOverride {
 /**
  * Parent resource configuration for nested routes
  *
- * Defines the parent resource relationship for generating nested REST routes
+ * Defines a single parent resource relationship for generating nested REST routes
  * like `/posts/:postId/comments/:id`.
  *
  * @example
@@ -207,16 +207,39 @@ export interface RestRouteOverride {
  */
 export interface ParentResourceConfig {
     /**
-     * Parent resource namespace (e.g., 'posts', 'users')
-     * Used to build the parent path segment: `/${namespace}/:${paramName}`
+     * Parent resource name (e.g., 'posts', 'users')
+     * Used to build the parent path segment: `/${resource}/:${param}`
      */
-    readonly namespace: string;
+    readonly resource: string;
     /**
      * Parent resource parameter name in the path
-     * Defaults to `${singularNamespace}Id` if not specified
+     * Defaults to `${singularResource}Id` if not specified
      * (e.g., 'posts' -> 'postId', 'users' -> 'userId')
      */
-    readonly paramName: string;
+    readonly param: string;
+}
+/**
+ * Multi-level parent resource configuration for deeply nested routes
+ *
+ * Defines multiple parent resources for generating deeply nested REST routes
+ * like `/organizations/:orgId/projects/:projectId/tasks/:id`.
+ *
+ * @example
+ * ```typescript
+ * // Multi-level nesting
+ * procedure().parents([
+ *   { resource: 'organizations', param: 'orgId' },
+ *   { resource: 'projects', param: 'projectId' },
+ * ])
+ * // Generates: /organizations/:orgId/projects/:projectId/tasks/:id
+ * ```
+ */
+export interface ParentResourceChain {
+    /**
+     * Array of parent resources from outermost to innermost
+     * E.g., [organizations, projects] for /organizations/:orgId/projects/:projectId/tasks
+     */
+    readonly parents: readonly ParentResourceConfig[];
 }
 /**
  * Compiled procedure with all metadata and handlers
@@ -249,7 +272,7 @@ export interface CompiledProcedure<TInput = unknown, TOutput = unknown, TContext
     /** REST route override (if specified) */
     readonly restOverride?: RestRouteOverride;
     /**
-     * Parent resource configuration for nested routes
+     * Parent resource configuration for nested routes (single level)
      *
      * When specified, the REST path will be prefixed with the parent resource:
      * `/${parent.namespace}/:${parent.paramName}/${childNamespace}/:id`
@@ -262,6 +285,23 @@ export interface CompiledProcedure<TInput = unknown, TOutput = unknown, TContext
      * ```
      */
     readonly parentResource?: ParentResourceConfig;
+    /**
+     * Multi-level parent resource configuration for deeply nested routes
+     *
+     * When specified, the REST path will be prefixed with all parent resources:
+     * `/${parent1.namespace}/:${parent1.paramName}/${parent2.namespace}/:${parent2.paramName}/...`
+     *
+     * @example
+     * ```typescript
+     * // With parentResources: [
+     * //   { namespace: 'organizations', paramName: 'orgId' },
+     * //   { namespace: 'projects', paramName: 'projectId' }
+     * // ]
+     * // and namespace: 'tasks'
+     * // Generates: /organizations/:orgId/projects/:projectId/tasks/:id
+     * ```
+     */
+    readonly parentResources?: readonly ParentResourceConfig[];
     /**
      * Pre-compiled middleware chain executor
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veloxts/router",
-  "version": "0.6.83",
+  "version": "0.6.85",
   "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.83",
-    "@veloxts/validation": "0.6.83"
+    "@veloxts/core": "0.6.85",
+    "@veloxts/validation": "0.6.85"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "4.0.16",