@honestjs/rpc-plugin 1.4.1 → 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
@@ -41,12 +41,22 @@ interface SchemaInfo {
     readonly typescriptType?: string;
 }
 /**
- * Generated client file information
+ * Generated output information for one generator run.
  */
 interface GeneratedClientInfo {
-    readonly clientFile: string;
+    readonly generator: string;
+    readonly clientFile?: string;
+    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
@@ -72,6 +82,33 @@ declare class ApiError extends Error {
     constructor(statusCode: number, message: string);
 }
 
+/**
+ * Context passed to each RPC generator.
+ */
+interface RPCGeneratorContext {
+    readonly outputDir: string;
+    readonly routes: readonly ExtendedRouteInfo[];
+    readonly schemas: readonly SchemaInfo[];
+}
+/**
+ * Contract for custom RPC generators.
+ */
+interface RPCGenerator {
+    readonly name: string;
+    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
  */
@@ -80,6 +117,12 @@ interface RPCPluginOptions {
     readonly tsConfigPath?: string;
     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?: {
@@ -97,13 +140,19 @@ 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 clientGenerator;
+    private readonly generators;
     private project;
     private analyzedRoutes;
     private analyzedSchemas;
-    private generatedInfo;
+    private generatedInfos;
+    private diagnostics;
     private app;
     constructor(options?: RPCPluginOptions);
     /**
@@ -122,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
      */
@@ -135,13 +188,22 @@ declare class RPCPlugin implements IPlugin {
      * Get the generation info
      */
     getGenerationInfo(): GeneratedClientInfo | null;
+    /**
+     * 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;
     private publishArtifact;
     private getArtifactContextKey;
     /**
@@ -156,52 +218,65 @@ declare class RPCPlugin implements IPlugin {
      * Logs an error with the plugin prefix
      */
     private logError;
+    private logWarn;
+    private logDebug;
+    private canLog;
 }
 
 /**
- * Service for generating TypeScript RPC clients
+ * Built-in generator for TypeScript RPC clients.
  */
-declare class ClientGeneratorService {
+declare class TypeScriptClientGenerator implements RPCGenerator {
     private readonly outputDir;
+    readonly name = "typescript-client";
     constructor(outputDir: string);
     /**
-     * Generates the TypeScript RPC client
+     * Generates the TypeScript RPC client.
+     */
+    generate(context: RPCGeneratorContext): Promise<GeneratedClientInfo>;
+    /**
+     * Generates the TypeScript RPC client.
      */
     generateClient(routes: readonly ExtendedRouteInfo[], schemas: readonly SchemaInfo[]): Promise<GeneratedClientInfo>;
     /**
-     * Generates the main client file with types included
+     * Generates the main client file with types included.
      */
     private generateClientFile;
     /**
-     * Generates the client TypeScript content with types included
+     * Generates the client TypeScript content with types included.
      */
     private generateClientContent;
     /**
-     * Generates controller methods for the client
+     * Generates controller methods for the client.
      */
     private generateControllerMethods;
     /**
-     * Extracts the proper return type from route analysis
+     * Extracts the proper return type from route analysis.
      */
     private extractReturnType;
     /**
-     * Generates schema types from integrated schema generation
+     * 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
+     * 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
      */
@@ -210,6 +285,7 @@ declare class RouteAnalyzerService {
      * Finds controller classes in the project
      */
     private findControllerClasses;
+    private isControllerClass;
     /**
      * Processes all routes and extracts type information
      */
@@ -228,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
      */
@@ -277,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'>;
 /**
@@ -319,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: {
@@ -343,4 +434,4 @@ declare const BUILTIN_TYPES: Set<string>;
  */
 declare const GENERIC_TYPES: Set<string>;
 
-export { ApiError, BUILTIN_TYPES, BUILTIN_UTILITY_TYPES, type ChecksumData, ClientGeneratorService, 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, 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
@@ -41,12 +41,22 @@ interface SchemaInfo {
     readonly typescriptType?: string;
 }
 /**
- * Generated client file information
+ * Generated output information for one generator run.
  */
 interface GeneratedClientInfo {
-    readonly clientFile: string;
+    readonly generator: string;
+    readonly clientFile?: string;
+    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
@@ -72,6 +82,33 @@ declare class ApiError extends Error {
     constructor(statusCode: number, message: string);
 }
 
+/**
+ * Context passed to each RPC generator.
+ */
+interface RPCGeneratorContext {
+    readonly outputDir: string;
+    readonly routes: readonly ExtendedRouteInfo[];
+    readonly schemas: readonly SchemaInfo[];
+}
+/**
+ * Contract for custom RPC generators.
+ */
+interface RPCGenerator {
+    readonly name: string;
+    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
  */
@@ -80,6 +117,12 @@ interface RPCPluginOptions {
     readonly tsConfigPath?: string;
     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?: {
@@ -97,13 +140,19 @@ 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 clientGenerator;
+    private readonly generators;
     private project;
     private analyzedRoutes;
     private analyzedSchemas;
-    private generatedInfo;
+    private generatedInfos;
+    private diagnostics;
     private app;
     constructor(options?: RPCPluginOptions);
     /**
@@ -122,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
      */
@@ -135,13 +188,22 @@ declare class RPCPlugin implements IPlugin {
      * Get the generation info
      */
     getGenerationInfo(): GeneratedClientInfo | null;
+    /**
+     * 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;
     private publishArtifact;
     private getArtifactContextKey;
     /**
@@ -156,52 +218,65 @@ declare class RPCPlugin implements IPlugin {
      * Logs an error with the plugin prefix
      */
     private logError;
+    private logWarn;
+    private logDebug;
+    private canLog;
 }
 
 /**
- * Service for generating TypeScript RPC clients
+ * Built-in generator for TypeScript RPC clients.
  */
-declare class ClientGeneratorService {
+declare class TypeScriptClientGenerator implements RPCGenerator {
     private readonly outputDir;
+    readonly name = "typescript-client";
     constructor(outputDir: string);
     /**
-     * Generates the TypeScript RPC client
+     * Generates the TypeScript RPC client.
+     */
+    generate(context: RPCGeneratorContext): Promise<GeneratedClientInfo>;
+    /**
+     * Generates the TypeScript RPC client.
      */
     generateClient(routes: readonly ExtendedRouteInfo[], schemas: readonly SchemaInfo[]): Promise<GeneratedClientInfo>;
     /**
-     * Generates the main client file with types included
+     * Generates the main client file with types included.
      */
     private generateClientFile;
     /**
-     * Generates the client TypeScript content with types included
+     * Generates the client TypeScript content with types included.
      */
     private generateClientContent;
     /**
-     * Generates controller methods for the client
+     * Generates controller methods for the client.
      */
     private generateControllerMethods;
     /**
-     * Extracts the proper return type from route analysis
+     * Extracts the proper return type from route analysis.
      */
     private extractReturnType;
     /**
-     * Generates schema types from integrated schema generation
+     * 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
+     * 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
      */
@@ -210,6 +285,7 @@ declare class RouteAnalyzerService {
      * Finds controller classes in the project
      */
     private findControllerClasses;
+    private isControllerClass;
     /**
      * Processes all routes and extracts type information
      */
@@ -228,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
      */
@@ -277,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'>;
 /**
@@ -319,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: {
@@ -343,4 +434,4 @@ declare const BUILTIN_TYPES: Set<string>;
  */
 declare const GENERIC_TYPES: Set<string>;
 
-export { ApiError, BUILTIN_TYPES, BUILTIN_UTILITY_TYPES, type ChecksumData, ClientGeneratorService, 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, 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 };