@honestjs/rpc-plugin 1.5.0 → 1.6.0

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