@veloxts/router 0.6.84 → 0.6.86

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;
+}

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