@honestjs/rpc-plugin 1.5.0 → 1.6.1

package/README.md

@@ -36,6 +36,11 @@ interface RPCPluginOptions {
 	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 keys?: {
@@ -65,12 +70,14 @@ After analysis, RPC plugin publishes this artifact to the application context:
 
 ```typescript
 type RpcArtifact = {
+	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'
@@ -80,15 +87,18 @@ const { hono } = await Application.create(AppModule, {
 })
 ```
 
+`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`)
 
@@ -228,24 +238,25 @@ expect(mockFetch).toHaveBeenCalledWith('http://test.com/api/v1/users/123', expec
 
 ## 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.
 
-> **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
 
@@ -324,8 +335,11 @@ You can also manually trigger generation:
 
 ```typescript
 const rpcPlugin = new RPCPlugin()
-await rpcPlugin.analyze() // Force regeneration (bypasses cache)
-await rpcPlugin.analyze(false) // Respect cache
+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
@@ -361,7 +375,7 @@ 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
@@ -403,7 +417,7 @@ import { UsersService } from './users.service'
 
 @Module({
 	controllers: [UsersController],
-	providers: [UsersService]
+	services: [UsersService]
 })
 export class UsersModule {}
 ```

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { RouteInfo, ParameterMetadata, IPlugin, Application } from 'honestjs';
 import { Hono } from 'hono';
-import { Project, Type } from 'ts-morph';
+import { ClassDeclaration, Project, Type } from 'ts-morph';
 
 /**
  * Parameter metadata with enhanced type information
@@ -49,6 +49,14 @@ interface GeneratedClientInfo {
     readonly outputFiles?: readonly string[];
     readonly generatedAt: string;
 }
+/**
+ * Serialized artifact produced by RPCPlugin and published to application context.
+ */
+interface RpcArtifact {
+    readonly artifactVersion: string;
+    readonly routes: readonly ExtendedRouteInfo[];
+    readonly schemas: readonly SchemaInfo[];
+}
 
 /**
  * Clean separation of concerns for request options
@@ -90,6 +98,17 @@ interface RPCGenerator {
     generate(context: RPCGeneratorContext): Promise<GeneratedClientInfo>;
 }
 
+type RPCMode = 'strict' | 'best-effort';
+type RPCLogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
+interface RPCDiagnostics {
+    readonly generatedAt: string;
+    readonly mode: RPCMode;
+    readonly dryRun: boolean;
+    readonly cache: 'hit' | 'miss' | 'bypass';
+    readonly routesCount: number;
+    readonly schemasCount: number;
+    readonly warnings: readonly string[];
+}
 /**
  * Configuration options for the RPCPlugin
  */
@@ -99,6 +118,11 @@ interface RPCPluginOptions {
     readonly outputDir?: string;
     readonly generateOnInit?: boolean;
     readonly generators?: readonly RPCGenerator[];
+    readonly mode?: RPCMode;
+    readonly logLevel?: RPCLogLevel;
+    readonly customClassMatcher?: (classDeclaration: ClassDeclaration) => boolean;
+    readonly failOnSchemaError?: boolean;
+    readonly failOnRouteAnalysisWarning?: boolean;
     readonly context?: {
         readonly namespace?: string;
         readonly keys?: {
@@ -116,6 +140,11 @@ declare class RPCPlugin implements IPlugin {
     private readonly generateOnInit;
     private readonly contextNamespace;
     private readonly contextArtifactKey;
+    private readonly mode;
+    private readonly logLevel;
+    private readonly failOnSchemaError;
+    private readonly failOnRouteAnalysisWarning;
+    private readonly customClassMatcher?;
     private readonly routeAnalyzer;
     private readonly schemaGenerator;
     private readonly generators;
@@ -123,6 +152,7 @@ declare class RPCPlugin implements IPlugin {
     private analyzedRoutes;
     private analyzedSchemas;
     private generatedInfos;
+    private diagnostics;
     private app;
     constructor(options?: RPCPluginOptions);
     /**
@@ -141,7 +171,11 @@ declare class RPCPlugin implements IPlugin {
      * Manually trigger analysis (useful for testing or re-generation).
      * Defaults to force=true to bypass cache; pass false to use caching.
      */
-    analyze(force?: boolean): Promise<void>;
+    analyze(force: boolean): Promise<void>;
+    analyze(options: {
+        force?: boolean;
+        dryRun?: boolean;
+    }): Promise<void>;
     /**
      * Get the analyzed routes
      */
@@ -158,12 +192,15 @@ declare class RPCPlugin implements IPlugin {
      * Get all generation infos
      */
     getGenerationInfos(): readonly GeneratedClientInfo[];
+    getDiagnostics(): RPCDiagnostics | null;
     /**
      * Checks whether expected output files exist on disk
      */
     private outputFilesExist;
     private getArtifactPath;
+    private getDiagnosticsPath;
     private writeArtifactToDisk;
+    private writeDiagnosticsToDisk;
     private loadArtifactFromDisk;
     private runGenerators;
     private hasTypeScriptGenerator;
@@ -181,6 +218,9 @@ declare class RPCPlugin implements IPlugin {
      * Logs an error with the plugin prefix
      */
     private logError;
+    private logWarn;
+    private logDebug;
+    private canLog;
 }
 
 /**
@@ -218,20 +258,25 @@ declare class TypeScriptClientGenerator implements RPCGenerator {
      * Generates schema types from integrated schema generation.
      */
     private generateSchemaTypes;
-    /**
-     * Groups routes by controller for better organization.
-     */
-    private groupRoutesByController;
     /**
      * Analyzes route parameters to determine their types and usage.
      */
     private analyzeRouteParameters;
 }
 
+interface RouteAnalyzerOptions {
+    readonly customClassMatcher?: (classDeclaration: ClassDeclaration) => boolean;
+    readonly onWarn?: (message: string, details?: unknown) => void;
+}
 /**
  * Service for analyzing controller methods and extracting type information
  */
 declare class RouteAnalyzerService {
+    private readonly customClassMatcher?;
+    private readonly onWarn?;
+    private warnings;
+    constructor(options?: RouteAnalyzerOptions);
+    getWarnings(): readonly string[];
     /**
      * Analyzes controller methods to extract type information
      */
@@ -240,6 +285,7 @@ declare class RouteAnalyzerService {
      * Finds controller classes in the project
      */
     private findControllerClasses;
+    private isControllerClass;
     /**
      * Processes all routes and extracts type information
      */
@@ -258,13 +304,21 @@ declare class RouteAnalyzerService {
     private getParametersWithTypes;
 }
 
+interface SchemaGeneratorOptions {
+    readonly failOnSchemaError?: boolean;
+    readonly onWarn?: (message: string, details?: unknown) => void;
+}
 /**
  * Service for generating JSON schemas from TypeScript types used in controllers
  */
 declare class SchemaGeneratorService {
     private readonly controllerPattern;
     private readonly tsConfigPath;
-    constructor(controllerPattern: string, tsConfigPath: string);
+    private readonly failOnSchemaError;
+    private readonly onWarn?;
+    private warnings;
+    constructor(controllerPattern: string, tsConfigPath: string, options?: SchemaGeneratorOptions);
+    getWarnings(): readonly string[];
     /**
      * Generates JSON schemas from types used in controllers
      */
@@ -307,6 +361,10 @@ declare function readChecksum(outputDir: string): ChecksumData | null;
  */
 declare function writeChecksum(outputDir: string, data: ChecksumData): Promise<void>;
 
+declare const RPC_ARTIFACT_VERSION = "1";
+declare function isRpcArtifact(value: unknown): value is RpcArtifact;
+declare function assertRpcArtifact(value: unknown): asserts value is RpcArtifact;
+
 /** Minimal route shape needed to build the full API path (prefix + version + route + path). */
 type RoutePathInput = Pick<ExtendedRouteInfo, 'prefix' | 'version' | 'route' | 'path'>;
 /**
@@ -349,6 +407,9 @@ declare const DEFAULT_OPTIONS: {
     readonly tsConfigPath: "tsconfig.json";
     readonly outputDir: "./generated/rpc";
     readonly generateOnInit: true;
+    readonly mode: "best-effort";
+    readonly logLevel: "info";
+    readonly artifactVersion: "1";
     readonly context: {
         readonly namespace: "rpc";
         readonly keys: {
@@ -373,4 +434,4 @@ declare const BUILTIN_TYPES: Set<string>;
  */
 declare const GENERIC_TYPES: Set<string>;
 
-export { ApiError, BUILTIN_TYPES, BUILTIN_UTILITY_TYPES, type ChecksumData, type ControllerGroups, DEFAULT_OPTIONS, type ExtendedRouteInfo, type FetchFunction, GENERIC_TYPES, type GeneratedClientInfo, LOG_PREFIX, type ParameterMetadataWithType, RPCPlugin, type RPCPluginOptions, type RequestOptions, RouteAnalyzerService, type RouteParameter, type RoutePathInput, SchemaGeneratorService, type SchemaInfo, TypeScriptClientGenerator, buildFullApiPath, buildFullPath, camelCase, computeHash, extractNamedType, generateTypeScriptInterface, mapJsonSchemaTypeToTypeScript, readChecksum, safeToString, writeChecksum };
+export { ApiError, BUILTIN_TYPES, BUILTIN_UTILITY_TYPES, type ChecksumData, type ControllerGroups, DEFAULT_OPTIONS, type ExtendedRouteInfo, type FetchFunction, GENERIC_TYPES, type GeneratedClientInfo, LOG_PREFIX, type ParameterMetadataWithType, type RPCGenerator, type RPCGeneratorContext, RPCPlugin, type RPCPluginOptions, RPC_ARTIFACT_VERSION, type RequestOptions, RouteAnalyzerService, type RouteParameter, type RoutePathInput, SchemaGeneratorService, type SchemaInfo, TypeScriptClientGenerator, assertRpcArtifact, buildFullApiPath, buildFullPath, camelCase, computeHash, extractNamedType, generateTypeScriptInterface, isRpcArtifact, mapJsonSchemaTypeToTypeScript, readChecksum, safeToString, writeChecksum };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { RouteInfo, ParameterMetadata, IPlugin, Application } from 'honestjs';
 import { Hono } from 'hono';
-import { Project, Type } from 'ts-morph';
+import { ClassDeclaration, Project, Type } from 'ts-morph';
 
 /**
  * Parameter metadata with enhanced type information
@@ -49,6 +49,14 @@ interface GeneratedClientInfo {
     readonly outputFiles?: readonly string[];
     readonly generatedAt: string;
 }
+/**
+ * Serialized artifact produced by RPCPlugin and published to application context.
+ */
+interface RpcArtifact {
+    readonly artifactVersion: string;
+    readonly routes: readonly ExtendedRouteInfo[];
+    readonly schemas: readonly SchemaInfo[];
+}
 
 /**
  * Clean separation of concerns for request options
@@ -90,6 +98,17 @@ interface RPCGenerator {
     generate(context: RPCGeneratorContext): Promise<GeneratedClientInfo>;
 }
 
+type RPCMode = 'strict' | 'best-effort';
+type RPCLogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
+interface RPCDiagnostics {
+    readonly generatedAt: string;
+    readonly mode: RPCMode;
+    readonly dryRun: boolean;
+    readonly cache: 'hit' | 'miss' | 'bypass';
+    readonly routesCount: number;
+    readonly schemasCount: number;
+    readonly warnings: readonly string[];
+}
 /**
  * Configuration options for the RPCPlugin
  */
@@ -99,6 +118,11 @@ interface RPCPluginOptions {
     readonly outputDir?: string;
     readonly generateOnInit?: boolean;
     readonly generators?: readonly RPCGenerator[];
+    readonly mode?: RPCMode;
+    readonly logLevel?: RPCLogLevel;
+    readonly customClassMatcher?: (classDeclaration: ClassDeclaration) => boolean;
+    readonly failOnSchemaError?: boolean;
+    readonly failOnRouteAnalysisWarning?: boolean;
     readonly context?: {
         readonly namespace?: string;
         readonly keys?: {
@@ -116,6 +140,11 @@ declare class RPCPlugin implements IPlugin {
     private readonly generateOnInit;
     private readonly contextNamespace;
     private readonly contextArtifactKey;
+    private readonly mode;
+    private readonly logLevel;
+    private readonly failOnSchemaError;
+    private readonly failOnRouteAnalysisWarning;
+    private readonly customClassMatcher?;
     private readonly routeAnalyzer;
     private readonly schemaGenerator;
     private readonly generators;
@@ -123,6 +152,7 @@ declare class RPCPlugin implements IPlugin {
     private analyzedRoutes;
     private analyzedSchemas;
     private generatedInfos;
+    private diagnostics;
     private app;
     constructor(options?: RPCPluginOptions);
     /**
@@ -141,7 +171,11 @@ declare class RPCPlugin implements IPlugin {
      * Manually trigger analysis (useful for testing or re-generation).
      * Defaults to force=true to bypass cache; pass false to use caching.
      */
-    analyze(force?: boolean): Promise<void>;
+    analyze(force: boolean): Promise<void>;
+    analyze(options: {
+        force?: boolean;
+        dryRun?: boolean;
+    }): Promise<void>;
     /**
      * Get the analyzed routes
      */
@@ -158,12 +192,15 @@ declare class RPCPlugin implements IPlugin {
      * Get all generation infos
      */
     getGenerationInfos(): readonly GeneratedClientInfo[];
+    getDiagnostics(): RPCDiagnostics | null;
     /**
      * Checks whether expected output files exist on disk
      */
     private outputFilesExist;
     private getArtifactPath;
+    private getDiagnosticsPath;
     private writeArtifactToDisk;
+    private writeDiagnosticsToDisk;
     private loadArtifactFromDisk;
     private runGenerators;
     private hasTypeScriptGenerator;
@@ -181,6 +218,9 @@ declare class RPCPlugin implements IPlugin {
      * Logs an error with the plugin prefix
      */
     private logError;
+    private logWarn;
+    private logDebug;
+    private canLog;
 }
 
 /**
@@ -218,20 +258,25 @@ declare class TypeScriptClientGenerator implements RPCGenerator {
      * Generates schema types from integrated schema generation.
      */
     private generateSchemaTypes;
-    /**
-     * Groups routes by controller for better organization.
-     */
-    private groupRoutesByController;
     /**
      * Analyzes route parameters to determine their types and usage.
      */
     private analyzeRouteParameters;
 }
 
+interface RouteAnalyzerOptions {
+    readonly customClassMatcher?: (classDeclaration: ClassDeclaration) => boolean;
+    readonly onWarn?: (message: string, details?: unknown) => void;
+}
 /**
  * Service for analyzing controller methods and extracting type information
  */
 declare class RouteAnalyzerService {
+    private readonly customClassMatcher?;
+    private readonly onWarn?;
+    private warnings;
+    constructor(options?: RouteAnalyzerOptions);
+    getWarnings(): readonly string[];
     /**
      * Analyzes controller methods to extract type information
      */
@@ -240,6 +285,7 @@ declare class RouteAnalyzerService {
      * Finds controller classes in the project
      */
     private findControllerClasses;
+    private isControllerClass;
     /**
      * Processes all routes and extracts type information
      */
@@ -258,13 +304,21 @@ declare class RouteAnalyzerService {
     private getParametersWithTypes;
 }
 
+interface SchemaGeneratorOptions {
+    readonly failOnSchemaError?: boolean;
+    readonly onWarn?: (message: string, details?: unknown) => void;
+}
 /**
  * Service for generating JSON schemas from TypeScript types used in controllers
  */
 declare class SchemaGeneratorService {
     private readonly controllerPattern;
     private readonly tsConfigPath;
-    constructor(controllerPattern: string, tsConfigPath: string);
+    private readonly failOnSchemaError;
+    private readonly onWarn?;
+    private warnings;
+    constructor(controllerPattern: string, tsConfigPath: string, options?: SchemaGeneratorOptions);
+    getWarnings(): readonly string[];
     /**
      * Generates JSON schemas from types used in controllers
      */
@@ -307,6 +361,10 @@ declare function readChecksum(outputDir: string): ChecksumData | null;
  */
 declare function writeChecksum(outputDir: string, data: ChecksumData): Promise<void>;
 
+declare const RPC_ARTIFACT_VERSION = "1";
+declare function isRpcArtifact(value: unknown): value is RpcArtifact;
+declare function assertRpcArtifact(value: unknown): asserts value is RpcArtifact;
+
 /** Minimal route shape needed to build the full API path (prefix + version + route + path). */
 type RoutePathInput = Pick<ExtendedRouteInfo, 'prefix' | 'version' | 'route' | 'path'>;
 /**
@@ -349,6 +407,9 @@ declare const DEFAULT_OPTIONS: {
     readonly tsConfigPath: "tsconfig.json";
     readonly outputDir: "./generated/rpc";
     readonly generateOnInit: true;
+    readonly mode: "best-effort";
+    readonly logLevel: "info";
+    readonly artifactVersion: "1";
     readonly context: {
         readonly namespace: "rpc";
         readonly keys: {
@@ -373,4 +434,4 @@ declare const BUILTIN_TYPES: Set<string>;
  */
 declare const GENERIC_TYPES: Set<string>;
 
-export { ApiError, BUILTIN_TYPES, BUILTIN_UTILITY_TYPES, type ChecksumData, type ControllerGroups, DEFAULT_OPTIONS, type ExtendedRouteInfo, type FetchFunction, GENERIC_TYPES, type GeneratedClientInfo, LOG_PREFIX, type ParameterMetadataWithType, RPCPlugin, type RPCPluginOptions, type RequestOptions, RouteAnalyzerService, type RouteParameter, type RoutePathInput, SchemaGeneratorService, type SchemaInfo, TypeScriptClientGenerator, buildFullApiPath, buildFullPath, camelCase, computeHash, extractNamedType, generateTypeScriptInterface, mapJsonSchemaTypeToTypeScript, readChecksum, safeToString, writeChecksum };
+export { ApiError, BUILTIN_TYPES, BUILTIN_UTILITY_TYPES, type ChecksumData, type ControllerGroups, DEFAULT_OPTIONS, type ExtendedRouteInfo, type FetchFunction, GENERIC_TYPES, type GeneratedClientInfo, LOG_PREFIX, type ParameterMetadataWithType, type RPCGenerator, type RPCGeneratorContext, RPCPlugin, type RPCPluginOptions, RPC_ARTIFACT_VERSION, type RequestOptions, RouteAnalyzerService, type RouteParameter, type RoutePathInput, SchemaGeneratorService, type SchemaInfo, TypeScriptClientGenerator, assertRpcArtifact, buildFullApiPath, buildFullPath, camelCase, computeHash, extractNamedType, generateTypeScriptInterface, isRpcArtifact, mapJsonSchemaTypeToTypeScript, readChecksum, safeToString, writeChecksum };