@honestjs/rpc-plugin 1.5.0 → 1.6.0

package/README.md

@@ -1,7 +1,8 @@
 # RPC Plugin
 
-The RPC Plugin automatically analyzes your HonestJS controllers and, by default, generates a fully-typed TypeScript RPC
-client with proper parameter typing. You can also provide custom generators.
+The RPC Plugin automatically analyzes your HonestJS controllers and, by default,
+generates a fully-typed TypeScript RPC client with proper parameter typing. You
+can also provide custom generators.
 
 ## Installation
 
@@ -16,47 +17,55 @@ pnpm add @honestjs/rpc-plugin
 ## Basic Setup
 
 ```typescript
-import { RPCPlugin } from '@honestjs/rpc-plugin'
-import { Application } from 'honestjs'
-import AppModule from './app.module'
+import { RPCPlugin } from "@honestjs/rpc-plugin";
+import { Application } from "honestjs";
+import AppModule from "./app.module";
 
 const { hono } = await Application.create(AppModule, {
-	plugins: [new RPCPlugin()]
-})
+	plugins: [new RPCPlugin()],
+});
 
-export default hono
+export default hono;
 ```
 
 ## Configuration Options
 
 ```typescript
 interface RPCPluginOptions {
-	readonly controllerPattern?: string // Glob pattern for controller files (default: 'src/modules/*/*.controller.ts')
-	readonly tsConfigPath?: string // Path to tsconfig.json (default: 'tsconfig.json')
-	readonly outputDir?: string // Output directory for generated files (default: './generated/rpc')
-	readonly generateOnInit?: boolean // Generate files on initialization (default: true)
-	readonly generators?: readonly RPCGenerator[] // Optional list of generators to execute
+	readonly controllerPattern?: string; // Glob pattern for controller files (default: 'src/modules/*/*.controller.ts')
+	readonly tsConfigPath?: string; // Path to tsconfig.json (default: 'tsconfig.json')
+	readonly outputDir?: string; // Output directory for generated files (default: './generated/rpc')
+	readonly generateOnInit?: boolean; // Generate files on initialization (default: true)
+	readonly generators?: readonly RPCGenerator[]; // Optional list of generators to execute
+	readonly mode?: "strict" | "best-effort"; // strict fails on warnings/fallbacks
+	readonly logLevel?: "silent" | "error" | "warn" | "info" | "debug"; // default: info
+	readonly customClassMatcher?: (
+		classDeclaration: ClassDeclaration,
+	) => boolean; // optional override; default discovery uses decorators
+	readonly failOnSchemaError?: boolean; // default true in strict mode
+	readonly failOnRouteAnalysisWarning?: boolean; // default true in strict mode
 	readonly context?: {
-		readonly namespace?: string // Default: 'rpc'
+		readonly namespace?: string; // Default: 'rpc'
 		readonly keys?: {
-			readonly artifact?: string // Default: 'artifact'
-		}
-	}
+			readonly artifact?: string; // Default: 'artifact'
+		};
+	};
 }
 ```
 
 ### Generator Behavior
 
-- If `generators` is omitted, the plugin uses the built-in `TypeScriptClientGenerator` by default.
+- If `generators` is omitted, the plugin uses the built-in
+  `TypeScriptClientGenerator` by default.
 - If `generators` is provided, only those generators are executed.
 - You can still use the built-in TypeScript client generator explicitly:
 
 ```typescript
-import { RPCPlugin, TypeScriptClientGenerator } from '@honestjs/rpc-plugin'
+import { RPCPlugin, TypeScriptClientGenerator } from "@honestjs/rpc-plugin";
 
 new RPCPlugin({
-	generators: [new TypeScriptClientGenerator('./generated/rpc')]
-})
+	generators: [new TypeScriptClientGenerator("./generated/rpc")],
+});
 ```
 
 ## Application Context Artifact
@@ -65,68 +74,78 @@ After analysis, RPC plugin publishes this artifact to the application context:
 
 ```typescript
 type RpcArtifact = {
-	routes: ExtendedRouteInfo[]
-	schemas: SchemaInfo[]
-}
+	artifactVersion: string;
+	routes: ExtendedRouteInfo[];
+	schemas: SchemaInfo[];
+};
 ```
 
-Default key is `'rpc.artifact'` (from `context.namespace + '.' + context.keys.artifact`). This enables direct integration with API docs:
+Default key is `'rpc.artifact'` (from
+`context.namespace + '.' + context.keys.artifact`). This enables direct
+integration with API docs:
 
 ```typescript
-import { ApiDocsPlugin } from '@honestjs/api-docs-plugin'
+import { ApiDocsPlugin } from "@honestjs/api-docs-plugin";
 
 const { hono } = await Application.create(AppModule, {
-	plugins: [new RPCPlugin(), new ApiDocsPlugin({ artifact: 'rpc.artifact' })]
-})
+	plugins: [new RPCPlugin(), new ApiDocsPlugin({ artifact: "rpc.artifact" })],
+});
 ```
 
+`artifactVersion` is currently `"1"` and is used for compatibility checks.
+
 ## What It Generates
 
 The plugin generates files in the output directory (default: `./generated/rpc`):
 
-| File            | Description                                  | When generated        |
-| --------------- | -------------------------------------------- | --------------------- |
-| `client.ts`     | Type-safe RPC client with all DTOs           | When TypeScript generator runs |
-| `.rpc-checksum` | Hash of source files for incremental caching | Always                |
-| `rpc-artifact.json` | Serialized routes/schemas artifact for cache-backed context publishing | Always |
+| File                   | Description                                                            | When generated                 |
+| ---------------------- | ---------------------------------------------------------------------- | ------------------------------ |
+| `client.ts`            | Type-safe RPC client with all DTOs                                     | When TypeScript generator runs |
+| `.rpc-checksum`        | Hash of source files for incremental caching                           | Always                         |
+| `rpc-artifact.json`    | Serialized routes/schemas artifact for cache-backed context publishing | Always                         |
+| `rpc-diagnostics.json` | Diagnostics report (mode, warnings, cache status)                      | Always                         |
 
 ### TypeScript RPC Client (`client.ts`)
 
-The plugin generates a single comprehensive file that includes both the client and all type definitions:
+The plugin generates a single comprehensive file that includes both the client
+and all type definitions:
 
 - **Controller-based organization**: Methods grouped by controller
 - **Type-safe parameters**: Path, query, and body parameters with proper typing
-- **Flexible request options**: Clean separation of params, query, body, and headers
+- **Flexible request options**: Clean separation of params, query, body, and
+  headers
 - **Error handling**: Built-in error handling with custom ApiError class
 - **Header management**: Easy custom header management
-- **Custom fetch support**: Inject custom fetch implementations for testing, middleware, and compatibility
-- **Integrated types**: All DTOs, interfaces, and utility types included in the same file
+- **Custom fetch support**: Inject custom fetch implementations for testing,
+  middleware, and compatibility
+- **Integrated types**: All DTOs, interfaces, and utility types included in the
+  same file
 
 ```typescript
 // Generated client usage
-import { ApiClient } from './generated/rpc/client'
+import { ApiClient } from "./generated/rpc/client";
 
 // Create client instance with base URL
-const apiClient = new ApiClient('http://localhost:3000')
+const apiClient = new ApiClient("http://localhost:3000");
 
 // Type-safe API calls
 const user = await apiClient.users.create({
-	body: { name: 'John', email: 'john@example.com' }
-})
+	body: { name: "John", email: "john@example.com" },
+});
 
 const users = await apiClient.users.list({
-	query: { page: 1, limit: 10 }
-})
+	query: { page: 1, limit: 10 },
+});
 
 const user = await apiClient.users.getById({
-	params: { id: '123' }
-})
+	params: { id: "123" },
+});
 
 // Set custom headers
 apiClient.setDefaultHeaders({
-	'X-API-Key': 'your-api-key',
-	Authorization: 'Bearer your-jwt-token'
-})
+	"X-API-Key": "your-api-key",
+	Authorization: "Bearer your-jwt-token",
+});
 ```
 
 The generated `client.ts` file contains everything you need:
@@ -142,7 +161,8 @@ The RPC client supports custom fetch implementations, which is useful for:
 
 - **Testing**: Inject mock fetch functions for unit testing
 - **Custom Logic**: Add logging, retries, or other middleware
-- **Environment Compatibility**: Use different fetch implementations (node-fetch, undici, etc.)
+- **Environment Compatibility**: Use different fetch implementations
+  (node-fetch, undici, etc.)
 - **Interceptors**: Wrap requests with custom logic before/after execution
 
 ### Basic Custom Fetch Example
@@ -150,13 +170,18 @@ The RPC client supports custom fetch implementations, which is useful for:
 ```typescript
 // Simple logging wrapper
 const loggingFetch = (input: RequestInfo | URL, init?: RequestInit) => {
-	console.log(`[${new Date().toISOString()}] Making ${init?.method || 'GET'} request to:`, input)
-	return fetch(input, init)
-}
-
-const apiClient = new ApiClient('http://localhost:3000', {
-	fetchFn: loggingFetch
-})
+	console.log(
+		`[${new Date().toISOString()}] Making ${
+			init?.method || "GET"
+		} request to:`,
+		input,
+	);
+	return fetch(input, init);
+};
+
+const apiClient = new ApiClient("http://localhost:3000", {
+	fetchFn: loggingFetch,
+});
 ```
 
 ### Advanced Custom Fetch Examples
@@ -167,24 +192,26 @@ const retryFetch = (maxRetries = 3) => {
 	return async (input: RequestInfo | URL, init?: RequestInit) => {
 		for (let i = 0; i <= maxRetries; i++) {
 			try {
-				const response = await fetch(input, init)
-				if (response.ok) return response
+				const response = await fetch(input, init);
+				if (response.ok) return response;
 
-				if (i === maxRetries) return response
+				if (i === maxRetries) return response;
 
 				// Wait with exponential backoff
-				await new Promise((resolve) => setTimeout(resolve, Math.pow(2, i) * 1000))
+				await new Promise((resolve) =>
+					setTimeout(resolve, Math.pow(2, i) * 1000)
+				);
 			} catch (error) {
-				if (i === maxRetries) throw error
+				if (i === maxRetries) throw error;
 			}
 		}
-		throw new Error('Max retries exceeded')
-	}
-}
+		throw new Error("Max retries exceeded");
+	};
+};
 
-const apiClientWithRetry = new ApiClient('http://localhost:3000', {
-	fetchFn: retryFetch(3)
-})
+const apiClientWithRetry = new ApiClient("http://localhost:3000", {
+	fetchFn: retryFetch(3),
+});
 
 // Request/response interceptor
 const interceptorFetch = (input: RequestInfo | URL, init?: RequestInit) => {
@@ -193,20 +220,20 @@ const interceptorFetch = (input: RequestInfo | URL, init?: RequestInit) => {
 		...init,
 		headers: {
 			...init?.headers,
-			'X-Request-ID': crypto.randomUUID()
-		}
-	}
+			"X-Request-ID": crypto.randomUUID(),
+		},
+	};
 
 	return fetch(input, enhancedInit).then((response) => {
 		// Post-response logic
-		console.log(`Response status: ${response.status}`)
-		return response
-	})
-}
-
-const apiClientWithInterceptor = new ApiClient('http://localhost:3000', {
-	fetchFn: interceptorFetch
-})
+		console.log(`Response status: ${response.status}`);
+		return response;
+	});
+};
+
+const apiClientWithInterceptor = new ApiClient("http://localhost:3000", {
+	fetchFn: interceptorFetch,
+});
 ```
 
 ### Testing with Custom Fetch
@@ -215,37 +242,45 @@ const apiClientWithInterceptor = new ApiClient('http://localhost:3000', {
 // Mock fetch for testing
 const mockFetch = jest.fn().mockResolvedValue({
 	ok: true,
-	json: () => Promise.resolve({ data: { id: '123', name: 'Test User' } })
-})
+	json: () => Promise.resolve({ data: { id: "123", name: "Test User" } }),
+});
 
-const testApiClient = new ApiClient('http://test.com', {
-	fetchFn: mockFetch
-})
+const testApiClient = new ApiClient("http://test.com", {
+	fetchFn: mockFetch,
+});
 
 // Your test can now verify the mock was called
-expect(mockFetch).toHaveBeenCalledWith('http://test.com/api/v1/users/123', expect.objectContaining({ method: 'GET' }))
+expect(mockFetch).toHaveBeenCalledWith(
+	"http://test.com/api/v1/users/123",
+	expect.objectContaining({ method: "GET" }),
+);
 ```
 
 ## Hash-based Caching
 
-On startup the plugin hashes all controller source files (SHA-256) and stores the checksum in `.rpc-checksum` inside the output directory. On subsequent runs, if the hash matches and the expected output files already exist, the expensive analysis and generation pipeline is skipped entirely. This significantly reduces startup time in large projects.
+On startup the plugin hashes all controller source files (SHA-256) and stores
+the checksum in `.rpc-checksum` inside the output directory. On subsequent runs,
+if the hash matches and the expected output files already exist, the expensive
+analysis and generation pipeline is skipped entirely. This significantly reduces
+startup time in large projects.
 
 Caching is automatic and requires no configuration. To force regeneration:
 
 ```typescript
-// Manual call — defaults to force=true, always regenerates
-await rpcPlugin.analyze()
-
 // Explicit cache bypass
-await rpcPlugin.analyze(true)
+await rpcPlugin.analyze({ force: true });
 
 // Respect the cache (same behavior as automatic startup)
-await rpcPlugin.analyze(false)
+await rpcPlugin.analyze({ force: false });
 ```
 
-You can also delete `.rpc-checksum` from the output directory to clear the cache.
+You can also delete `.rpc-checksum` from the output directory to clear the
+cache.
 
-> **Note:** The hash covers controller files matched by the `controllerPattern` glob. If you only change a DTO/model file that lives outside that pattern, the cache won't invalidate automatically. Use `analyze()` or delete `.rpc-checksum` in that case.
+> **Note:** The hash covers controller files matched by the `controllerPattern`
+> glob. If you only change a DTO/model file that lives outside that pattern, the
+> cache won't invalidate automatically. Use `analyze()` or delete
+> `.rpc-checksum` in that case.
 
 ## How It Works
 
@@ -285,21 +320,40 @@ export class ApiClient {
 	get users() {
 		return {
 			create: async <Result = User>(
-				options: RequestOptions<{ name: string; email: string }, undefined, undefined, undefined>
+				options: RequestOptions<
+					{ name: string; email: string },
+					undefined,
+					undefined,
+					undefined
+				>,
 			) => {
-				return this.request<Result>('POST', `/api/v1/users/`, options)
+				return this.request<Result>("POST", `/api/v1/users/`, options);
 			},
 			list: async <Result = User[]>(
-				options?: RequestOptions<undefined, { page: number; limit: number }, undefined, undefined>
+				options?: RequestOptions<
+					undefined,
+					{ page: number; limit: number },
+					undefined,
+					undefined
+				>,
 			) => {
-				return this.request<Result>('GET', `/api/v1/users/`, options)
+				return this.request<Result>("GET", `/api/v1/users/`, options);
 			},
 			getById: async <Result = User>(
-				options: RequestOptions<undefined, { id: string }, undefined, undefined>
+				options: RequestOptions<
+					undefined,
+					{ id: string },
+					undefined,
+					undefined
+				>,
 			) => {
-				return this.request<Result>('GET', `/api/v1/users/:id`, options)
-			}
-		}
+				return this.request<Result>(
+					"GET",
+					`/api/v1/users/:id`,
+					options,
+				);
+			},
+		};
 	}
 }
 
@@ -308,24 +362,29 @@ export type RequestOptions<
 	TParams = undefined,
 	TQuery = undefined,
 	TBody = undefined,
-	THeaders = undefined
-> = (TParams extends undefined ? object : { params: TParams }) &
-	(TQuery extends undefined ? object : { query: TQuery }) &
-	(TBody extends undefined ? object : { body: TBody }) &
-	(THeaders extends undefined ? object : { headers: THeaders })
+	THeaders = undefined,
+> =
+	& (TParams extends undefined ? object : { params: TParams })
+	& (TQuery extends undefined ? object : { query: TQuery })
+	& (TBody extends undefined ? object : { body: TBody })
+	& (THeaders extends undefined ? object : { headers: THeaders });
 ```
 
 ## Plugin Lifecycle
 
-The plugin automatically generates files when your HonestJS application starts up (if `generateOnInit` is true). On
-subsequent startups, the hash-based cache will skip regeneration if controller files haven't changed.
+The plugin automatically generates files when your HonestJS application starts
+up (if `generateOnInit` is true). On subsequent startups, the hash-based cache
+will skip regeneration if controller files haven't changed.
 
 You can also manually trigger generation:
 
 ```typescript
-const rpcPlugin = new RPCPlugin()
-await rpcPlugin.analyze() // Force regeneration (bypasses cache)
-await rpcPlugin.analyze(false) // Respect cache
+const rpcPlugin = new RPCPlugin();
+await rpcPlugin.analyze({ force: true }); // Force regeneration (bypasses cache)
+await rpcPlugin.analyze({ force: false }); // Respect cache
+
+// Analyze-only mode (no files generated, diagnostics still emitted)
+await rpcPlugin.analyze({ force: true, dryRun: true });
 ```
 
 ## Advanced Usage
@@ -336,9 +395,9 @@ If your controllers follow a different file structure:
 
 ```typescript
 new RPCPlugin({
-	controllerPattern: 'src/controllers/**/*.controller.ts',
-	outputDir: './src/generated/api'
-})
+	controllerPattern: "src/controllers/**/*.controller.ts",
+	outputDir: "./src/generated/api",
+});
 ```
 
 ### Manual Generation Control
@@ -347,11 +406,11 @@ Disable automatic generation and control when files are generated:
 
 ```typescript
 const rpcPlugin = new RPCPlugin({
-	generateOnInit: false
-})
+	generateOnInit: false,
+});
 
 // Later in your code
-await rpcPlugin.analyze()
+await rpcPlugin.analyze();
 ```
 
 ## Integration with HonestJS
@@ -361,32 +420,32 @@ await rpcPlugin.analyze()
 Here's how your controllers should be structured for optimal RPC generation:
 
 ```typescript
-import { Controller, Post, Get, Body, Param, Query } from 'honestjs'
+import { Body, Controller, Get, Param, Post, Query } from "honestjs";
 
 interface CreateUserDto {
-	name: string
-	email: string
+	name: string;
+	email: string;
 }
 
 interface ListUsersQuery {
-	page?: number
-	limit?: number
+	page?: number;
+	limit?: number;
 }
 
-@Controller('/users')
+@Controller("/users")
 export class UsersController {
-	@Post('/')
+	@Post("/")
 	async create(@Body() createUserDto: CreateUserDto): Promise<User> {
 		// Implementation
 	}
 
-	@Get('/')
+	@Get("/")
 	async list(@Query() query: ListUsersQuery): Promise<User[]> {
 		// Implementation
 	}
 
-	@Get('/:id')
-	async getById(@Param('id') id: string): Promise<User> {
+	@Get("/:id")
+	async getById(@Param("id") id: string): Promise<User> {
 		// Implementation
 	}
 }
@@ -397,13 +456,13 @@ export class UsersController {
 Ensure your controllers are properly registered in modules:
 
 ```typescript
-import { Module } from 'honestjs'
-import { UsersController } from './users.controller'
-import { UsersService } from './users.service'
+import { Module } from "honestjs";
+import { UsersController } from "./users.controller";
+import { UsersService } from "./users.service";
 
 @Module({
 	controllers: [UsersController],
-	providers: [UsersService]
+	services: [UsersService],
 })
 export class UsersModule {}
 ```
@@ -415,13 +474,13 @@ The generated client includes comprehensive error handling:
 ```typescript
 try {
 	const user = await apiClient.users.create({
-		body: { name: 'John', email: 'john@example.com' }
-	})
+		body: { name: "John", email: "john@example.com" },
+	});
 } catch (error) {
 	if (error instanceof ApiError) {
-		console.error(`API Error ${error.statusCode}: ${error.message}`)
+		console.error(`API Error ${error.statusCode}: ${error.message}`);
 	} else {
-		console.error('Unexpected error:', error)
+		console.error("Unexpected error:", error);
 	}
 }
 ```