@honestjs/rpc-plugin 1.4.0 → 1.5.0

package/README.md

@@ -1,7 +1,7 @@
 # RPC Plugin
 
-The RPC Plugin automatically analyzes your HonestJS controllers and generates a fully-typed TypeScript RPC client with
-proper parameter typing.
+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
 
@@ -35,6 +35,7 @@ interface RPCPluginOptions {
 	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 context?: {
 		readonly namespace?: string // Default: 'rpc'
 		readonly keys?: {
@@ -44,6 +45,20 @@ interface RPCPluginOptions {
 }
 ```
 
+### Generator Behavior
+
+- 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'
+
+new RPCPlugin({
+	generators: [new TypeScriptClientGenerator('./generated/rpc')]
+})
+```
+
 ## Application Context Artifact
 
 After analysis, RPC plugin publishes this artifact to the application context:
@@ -71,7 +86,7 @@ The plugin generates files in the output directory (default: `./generated/rpc`):
 
 | File            | Description                                  | When generated        |
 | --------------- | -------------------------------------------- | --------------------- |
-| `client.ts`     | Type-safe RPC client with all DTOs           | Always                |
+| `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 |
 

package/dist/index.d.mts

@@ -41,10 +41,12 @@ 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;
 }
 
@@ -72,6 +74,22 @@ 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>;
+}
+
 /**
  * Configuration options for the RPCPlugin
  */
@@ -80,6 +98,7 @@ interface RPCPluginOptions {
     readonly tsConfigPath?: string;
     readonly outputDir?: string;
     readonly generateOnInit?: boolean;
+    readonly generators?: readonly RPCGenerator[];
     readonly context?: {
         readonly namespace?: string;
         readonly keys?: {
@@ -99,11 +118,11 @@ declare class RPCPlugin implements IPlugin {
     private readonly contextArtifactKey;
     private readonly routeAnalyzer;
     private readonly schemaGenerator;
-    private readonly clientGenerator;
+    private readonly generators;
     private project;
     private analyzedRoutes;
     private analyzedSchemas;
-    private generatedInfo;
+    private generatedInfos;
     private app;
     constructor(options?: RPCPluginOptions);
     /**
@@ -135,6 +154,10 @@ declare class RPCPlugin implements IPlugin {
      * Get the generation info
      */
     getGenerationInfo(): GeneratedClientInfo | null;
+    /**
+     * Get all generation infos
+     */
+    getGenerationInfos(): readonly GeneratedClientInfo[];
     /**
      * Checks whether expected output files exist on disk
      */
@@ -142,6 +165,8 @@ declare class RPCPlugin implements IPlugin {
     private getArtifactPath;
     private writeArtifactToDisk;
     private loadArtifactFromDisk;
+    private runGenerators;
+    private hasTypeScriptGenerator;
     private publishArtifact;
     private getArtifactContextKey;
     /**
@@ -159,41 +184,46 @@ declare class RPCPlugin implements IPlugin {
 }
 
 /**
- * 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
+     * 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;
 }
@@ -277,6 +307,8 @@ declare function readChecksum(outputDir: string): ChecksumData | null;
  */
 declare function writeChecksum(outputDir: string, data: ChecksumData): Promise<void>;
 
+/** Minimal route shape needed to build the full API path (prefix + version + route + path). */
+type RoutePathInput = Pick<ExtendedRouteInfo, 'prefix' | 'version' | 'route' | 'path'>;
 /**
  * Builds the full path with parameter placeholders
  */
@@ -284,7 +316,7 @@ declare function buildFullPath(basePath: string, parameters: readonly ParameterM
 /**
  * Builds the full API path using route information
  */
-declare function buildFullApiPath(route: ExtendedRouteInfo): string;
+declare function buildFullApiPath(route: RoutePathInput): string;
 
 /**
  * Maps JSON schema types to TypeScript types
@@ -341,4 +373,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, 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, RPCPlugin, type RPCPluginOptions, type RequestOptions, RouteAnalyzerService, type RouteParameter, type RoutePathInput, SchemaGeneratorService, type SchemaInfo, TypeScriptClientGenerator, buildFullApiPath, buildFullPath, camelCase, computeHash, extractNamedType, generateTypeScriptInterface, mapJsonSchemaTypeToTypeScript, readChecksum, safeToString, writeChecksum };

package/dist/index.d.ts

@@ -41,10 +41,12 @@ 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;
 }
 
@@ -72,6 +74,22 @@ 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>;
+}
+
 /**
  * Configuration options for the RPCPlugin
  */
@@ -80,6 +98,7 @@ interface RPCPluginOptions {
     readonly tsConfigPath?: string;
     readonly outputDir?: string;
     readonly generateOnInit?: boolean;
+    readonly generators?: readonly RPCGenerator[];
     readonly context?: {
         readonly namespace?: string;
         readonly keys?: {
@@ -99,11 +118,11 @@ declare class RPCPlugin implements IPlugin {
     private readonly contextArtifactKey;
     private readonly routeAnalyzer;
     private readonly schemaGenerator;
-    private readonly clientGenerator;
+    private readonly generators;
     private project;
     private analyzedRoutes;
     private analyzedSchemas;
-    private generatedInfo;
+    private generatedInfos;
     private app;
     constructor(options?: RPCPluginOptions);
     /**
@@ -135,6 +154,10 @@ declare class RPCPlugin implements IPlugin {
      * Get the generation info
      */
     getGenerationInfo(): GeneratedClientInfo | null;
+    /**
+     * Get all generation infos
+     */
+    getGenerationInfos(): readonly GeneratedClientInfo[];
     /**
      * Checks whether expected output files exist on disk
      */
@@ -142,6 +165,8 @@ declare class RPCPlugin implements IPlugin {
     private getArtifactPath;
     private writeArtifactToDisk;
     private loadArtifactFromDisk;
+    private runGenerators;
+    private hasTypeScriptGenerator;
     private publishArtifact;
     private getArtifactContextKey;
     /**
@@ -159,41 +184,46 @@ declare class RPCPlugin implements IPlugin {
 }
 
 /**
- * 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
+     * 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;
 }
@@ -277,6 +307,8 @@ declare function readChecksum(outputDir: string): ChecksumData | null;
  */
 declare function writeChecksum(outputDir: string, data: ChecksumData): Promise<void>;
 
+/** Minimal route shape needed to build the full API path (prefix + version + route + path). */
+type RoutePathInput = Pick<ExtendedRouteInfo, 'prefix' | 'version' | 'route' | 'path'>;
 /**
  * Builds the full path with parameter placeholders
  */
@@ -284,7 +316,7 @@ declare function buildFullPath(basePath: string, parameters: readonly ParameterM
 /**
  * Builds the full API path using route information
  */
-declare function buildFullApiPath(route: ExtendedRouteInfo): string;
+declare function buildFullApiPath(route: RoutePathInput): string;
 
 /**
  * Maps JSON schema types to TypeScript types
@@ -341,4 +373,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, 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, RPCPlugin, type RPCPluginOptions, type RequestOptions, RouteAnalyzerService, type RouteParameter, type RoutePathInput, SchemaGeneratorService, type SchemaInfo, TypeScriptClientGenerator, buildFullApiPath, buildFullPath, camelCase, computeHash, extractNamedType, generateTypeScriptInterface, mapJsonSchemaTypeToTypeScript, readChecksum, safeToString, writeChecksum };