@honestjs/rpc-plugin 1.2.0 → 1.3.0

package/README.md

@@ -32,11 +32,28 @@ 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 openapi?: OpenApiOptions | boolean // Enable OpenAPI spec generation (default: false)
+}
+
+interface OpenApiOptions {
+	readonly title?: string // API title (default: 'API')
+	readonly version?: string // API version (default: '1.0.0')
+	readonly description?: string // API description (default: '')
+	readonly servers?: readonly { url: string; description?: string }[] // Server list
+	readonly outputFile?: string // Output filename (default: 'openapi.json')
 }
 ```
 
 ## 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           | Always                |
+| `openapi.json`  | OpenAPI 3.0.3 specification                  | When `openapi` is set |
+| `.rpc-checksum` | Hash of source files for incremental caching | Always                |
+
 ### TypeScript RPC Client (`client.ts`)
 
 The plugin generates a single comprehensive file that includes both the client and all type definitions:
@@ -173,6 +190,67 @@ const testApiClient = new ApiClient('http://test.com', {
 expect(mockFetch).toHaveBeenCalledWith('http://test.com/api/v1/users/123', expect.objectContaining({ method: 'GET' }))
 ```
 
+## OpenAPI Spec Generation
+
+The plugin can produce an OpenAPI 3.0.3 JSON specification alongside the client. This is useful for Swagger UI, documentation portals, and third-party integrations. No extra dependencies are needed — the spec is built from the same route and schema data used for client generation.
+
+### Enable with defaults
+
+Pass `true` to use all default values:
+
+```typescript
+new RPCPlugin({
+	openapi: true
+})
+```
+
+### Custom options
+
+```typescript
+new RPCPlugin({
+	openapi: {
+		title: 'My Service API',
+		version: '2.1.0',
+		description: 'User management service',
+		servers: [
+			{ url: 'https://api.example.com', description: 'Production' },
+			{ url: 'http://localhost:3000', description: 'Local' }
+		],
+		outputFile: 'api-spec.json'
+	}
+})
+```
+
+The generated spec includes:
+
+- **Paths** derived from your controller routes
+- **Parameters** (path, query) with correct types
+- **Request bodies** referencing component schemas for DTOs
+- **Responses** with schema references and array type support
+- **Component schemas** extracted from `ts-json-schema-generator` output
+- **Tags** derived from controller names
+
+## 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.
+
+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)
+
+// Respect the cache (same behavior as automatic startup)
+await rpcPlugin.analyze(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.
+
 ## How It Works
 
 ### 1. Route Analysis
@@ -196,6 +274,19 @@ expect(mockFetch).toHaveBeenCalledWith('http://test.com/api/v1/users/123', expec
 - Creates parameter validation and typing
 - Builds the complete RPC client with proper error handling
 
+### 4. OpenAPI Generation (optional)
+
+- Converts route and schema data to OpenAPI 3.0.3 paths and components
+- Maps `@Param()`, `@Query()`, and `@Body()` decorators to the correct OpenAPI parameter locations
+- References component schemas via `$ref` for DTOs
+- Outputs a single JSON file ready for Swagger UI or any OpenAPI-compatible tool
+
+### 5. Incremental Caching
+
+- Hashes all matched controller files after glob resolution
+- Compares against the stored `.rpc-checksum`
+- Skips steps 1–4 when files are unchanged and output already exists
+
 ## Example Generated Output
 
 ### Generated Client
@@ -237,12 +328,15 @@ export type RequestOptions<
 
 ## Plugin Lifecycle
 
-The plugin automatically generates files when your HonestJS application starts up (if `generateOnInit` is true). You can
-also manually trigger generation:
+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() // Manually trigger analysis and generation
+await rpcPlugin.analyze() // Force regeneration (bypasses cache)
+await rpcPlugin.analyze(false) // Respect cache
 ```
 
 ## Advanced Usage

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { RouteInfo, ParameterMetadata, IPlugin, Application } from 'honestjs';
 import { Hono } from 'hono';
-import { Type } from 'ts-morph';
+import { Project, Type } from 'ts-morph';
 
 /**
  * Parameter metadata with enhanced type information
@@ -9,6 +9,8 @@ interface ParameterMetadataWithType extends ParameterMetadata {
     readonly type: string;
     readonly required: boolean;
     readonly name: string;
+    /** Original decorator kind: 'body', 'param', 'query', 'header', etc. */
+    readonly decoratorType: string;
 }
 /**
  * Extended route information with comprehensive type data
@@ -49,21 +51,13 @@ interface GeneratedClientInfo {
 /**
  * Clean separation of concerns for request options
  */
-type RequestOptions<TParams = never, TQuery = never, TBody = never, THeaders = never> = (TParams extends never ? {
-    params?: never;
-} : {
+type RequestOptions<TParams = undefined, TQuery = undefined, TBody = undefined, THeaders = undefined> = (TParams extends undefined ? object : {
     params: TParams;
-}) & (TQuery extends never ? {
-    query?: never;
-} : {
-    query?: TQuery;
-}) & (TBody extends never ? {
-    body?: never;
-} : {
+}) & (TQuery extends undefined ? object : {
+    query: TQuery;
+}) & (TBody extends undefined ? object : {
     body: TBody;
-}) & (THeaders extends never ? {
-    headers?: never;
-} : {
+}) & (THeaders extends undefined ? object : {
     headers: THeaders;
 });
 /**
@@ -78,6 +72,16 @@ declare class ApiError extends Error {
     constructor(statusCode: number, message: string);
 }
 
+interface OpenApiOptions {
+    readonly title?: string;
+    readonly version?: string;
+    readonly description?: string;
+    readonly servers?: readonly {
+        url: string;
+        description?: string;
+    }[];
+    readonly outputFile?: string;
+}
 /**
  * Configuration options for the RPCPlugin
  */
@@ -86,6 +90,7 @@ interface RPCPluginOptions {
     readonly tsConfigPath?: string;
     readonly outputDir?: string;
     readonly generateOnInit?: boolean;
+    readonly openapi?: OpenApiOptions | boolean;
 }
 /**
  * Comprehensive RPC plugin that combines route analysis, schema generation, and client generation
@@ -98,10 +103,14 @@ declare class RPCPlugin implements IPlugin {
     private readonly routeAnalyzer;
     private readonly schemaGenerator;
     private readonly clientGenerator;
+    private readonly openApiGenerator;
+    private readonly openApiOptions;
+    private project;
     private analyzedRoutes;
     private analyzedSchemas;
     private generatedInfo;
     constructor(options?: RPCPluginOptions);
+    private resolveOpenApiOptions;
     /**
      * Validates the plugin configuration
      */
@@ -115,9 +124,10 @@ declare class RPCPlugin implements IPlugin {
      */
     private analyzeEverything;
     /**
-     * Manually trigger analysis (useful for testing or re-generation)
+     * Manually trigger analysis (useful for testing or re-generation).
+     * Defaults to force=true to bypass cache; pass false to use caching.
      */
-    analyze(): Promise<void>;
+    analyze(force?: boolean): Promise<void>;
     /**
      * Get the analyzed routes
      */
@@ -130,6 +140,10 @@ declare class RPCPlugin implements IPlugin {
      * Get the generation info
      */
     getGenerationInfo(): GeneratedClientInfo | null;
+    /**
+     * Checks whether expected output files exist on disk
+     */
+    private outputFilesExist;
     /**
      * Cleanup resources to prevent memory leaks
      */
@@ -184,26 +198,50 @@ declare class ClientGeneratorService {
     private analyzeRouteParameters;
 }
 
+interface ResolvedOpenApiOptions {
+    readonly title: string;
+    readonly version: string;
+    readonly description: string;
+    readonly servers: readonly {
+        url: string;
+        description?: string;
+    }[];
+    readonly outputFile: string;
+}
 /**
- * Service for analyzing controller methods and extracting type information
+ * Service for generating OpenAPI 3.0.3 specifications from analyzed routes and schemas
  */
-declare class RouteAnalyzerService {
-    private readonly controllerPattern;
-    private readonly tsConfigPath;
-    constructor(controllerPattern: string, tsConfigPath: string);
-    private projects;
+declare class OpenApiGeneratorService {
+    private readonly outputDir;
+    constructor(outputDir: string);
+    generateSpec(routes: readonly ExtendedRouteInfo[], schemas: readonly SchemaInfo[], options: ResolvedOpenApiOptions): Promise<string>;
+    private buildSpec;
+    private buildOperation;
+    private buildParameters;
+    private buildRequestBody;
+    private buildResponses;
+    private resolveResponseSchema;
+    private buildSchemaMap;
     /**
-     * Analyzes controller methods to extract type information
+     * Converts Express-style `:param` path to OpenAPI `{param}` syntax
      */
-    analyzeControllerMethods(): Promise<ExtendedRouteInfo[]>;
+    private toOpenApiPath;
+    private tsTypeToJsonSchema;
     /**
-     * Creates a new ts-morph project
+     * Extracts the base type name from a TS type string, stripping
+     * wrappers like `Partial<...>`, `...[]`, `Promise<...>`.
      */
-    private createProject;
+    private extractBaseTypeName;
+}
+
+/**
+ * Service for analyzing controller methods and extracting type information
+ */
+declare class RouteAnalyzerService {
     /**
-     * Cleanup resources to prevent memory leaks
+     * Analyzes controller methods to extract type information
      */
-    dispose(): void;
+    analyzeControllerMethods(project: Project): Promise<ExtendedRouteInfo[]>;
     /**
      * Finds controller classes in the project
      */
@@ -233,19 +271,10 @@ declare class SchemaGeneratorService {
     private readonly controllerPattern;
     private readonly tsConfigPath;
     constructor(controllerPattern: string, tsConfigPath: string);
-    private projects;
     /**
      * Generates JSON schemas from types used in controllers
      */
-    generateSchemas(): Promise<SchemaInfo[]>;
-    /**
-     * Creates a new ts-morph project
-     */
-    private createProject;
-    /**
-     * Cleanup resources to prevent memory leaks
-     */
-    dispose(): void;
+    generateSchemas(project: Project): Promise<SchemaInfo[]>;
     /**
      * Collects types from controller files
      */
@@ -264,6 +293,26 @@ declare class SchemaGeneratorService {
     private generateSchemaForType;
 }
 
+interface ChecksumData {
+    hash: string;
+    files: string[];
+}
+/**
+ * Computes a deterministic SHA-256 hash from file contents.
+ * Sorts paths before reading to ensure consistent ordering.
+ * Includes the file count in the hash so adding/removing files changes it.
+ */
+declare function computeHash(filePaths: string[]): string;
+/**
+ * Reads the stored checksum from the output directory.
+ * Returns null if the file is missing or corrupt.
+ */
+declare function readChecksum(outputDir: string): ChecksumData | null;
+/**
+ * Writes the checksum data to the output directory.
+ */
+declare function writeChecksum(outputDir: string, data: ChecksumData): Promise<void>;
+
 /**
  * Builds the full path with parameter placeholders
  */
@@ -295,10 +344,6 @@ declare function camelCase(str: string): string;
  * Extracts a named type from a TypeScript type
  */
 declare function extractNamedType(type: Type): string | null;
-/**
- * Generates type imports for the client
- */
-declare function generateTypeImports(routes: readonly any[]): string;
 
 /**
  * Default configuration options for the RPCPlugin
@@ -326,4 +371,4 @@ declare const BUILTIN_TYPES: Set<string>;
  */
 declare const GENERIC_TYPES: Set<string>;
 
-export { ApiError, BUILTIN_TYPES, BUILTIN_UTILITY_TYPES, 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, extractNamedType, generateTypeImports, generateTypeScriptInterface, mapJsonSchemaTypeToTypeScript, safeToString };
+export { ApiError, BUILTIN_TYPES, BUILTIN_UTILITY_TYPES, type ChecksumData, ClientGeneratorService, type ControllerGroups, DEFAULT_OPTIONS, type ExtendedRouteInfo, type FetchFunction, GENERIC_TYPES, type GeneratedClientInfo, LOG_PREFIX, OpenApiGeneratorService, type OpenApiOptions, type ParameterMetadataWithType, RPCPlugin, type RPCPluginOptions, type RequestOptions, RouteAnalyzerService, type RouteParameter, SchemaGeneratorService, type SchemaInfo, buildFullApiPath, buildFullPath, camelCase, computeHash, extractNamedType, generateTypeScriptInterface, 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 { Type } from 'ts-morph';
+import { Project, Type } from 'ts-morph';
 
 /**
  * Parameter metadata with enhanced type information
@@ -9,6 +9,8 @@ interface ParameterMetadataWithType extends ParameterMetadata {
     readonly type: string;
     readonly required: boolean;
     readonly name: string;
+    /** Original decorator kind: 'body', 'param', 'query', 'header', etc. */
+    readonly decoratorType: string;
 }
 /**
  * Extended route information with comprehensive type data
@@ -49,21 +51,13 @@ interface GeneratedClientInfo {
 /**
  * Clean separation of concerns for request options
  */
-type RequestOptions<TParams = never, TQuery = never, TBody = never, THeaders = never> = (TParams extends never ? {
-    params?: never;
-} : {
+type RequestOptions<TParams = undefined, TQuery = undefined, TBody = undefined, THeaders = undefined> = (TParams extends undefined ? object : {
     params: TParams;
-}) & (TQuery extends never ? {
-    query?: never;
-} : {
-    query?: TQuery;
-}) & (TBody extends never ? {
-    body?: never;
-} : {
+}) & (TQuery extends undefined ? object : {
+    query: TQuery;
+}) & (TBody extends undefined ? object : {
     body: TBody;
-}) & (THeaders extends never ? {
-    headers?: never;
-} : {
+}) & (THeaders extends undefined ? object : {
     headers: THeaders;
 });
 /**
@@ -78,6 +72,16 @@ declare class ApiError extends Error {
     constructor(statusCode: number, message: string);
 }
 
+interface OpenApiOptions {
+    readonly title?: string;
+    readonly version?: string;
+    readonly description?: string;
+    readonly servers?: readonly {
+        url: string;
+        description?: string;
+    }[];
+    readonly outputFile?: string;
+}
 /**
  * Configuration options for the RPCPlugin
  */
@@ -86,6 +90,7 @@ interface RPCPluginOptions {
     readonly tsConfigPath?: string;
     readonly outputDir?: string;
     readonly generateOnInit?: boolean;
+    readonly openapi?: OpenApiOptions | boolean;
 }
 /**
  * Comprehensive RPC plugin that combines route analysis, schema generation, and client generation
@@ -98,10 +103,14 @@ declare class RPCPlugin implements IPlugin {
     private readonly routeAnalyzer;
     private readonly schemaGenerator;
     private readonly clientGenerator;
+    private readonly openApiGenerator;
+    private readonly openApiOptions;
+    private project;
     private analyzedRoutes;
     private analyzedSchemas;
     private generatedInfo;
     constructor(options?: RPCPluginOptions);
+    private resolveOpenApiOptions;
     /**
      * Validates the plugin configuration
      */
@@ -115,9 +124,10 @@ declare class RPCPlugin implements IPlugin {
      */
     private analyzeEverything;
     /**
-     * Manually trigger analysis (useful for testing or re-generation)
+     * Manually trigger analysis (useful for testing or re-generation).
+     * Defaults to force=true to bypass cache; pass false to use caching.
      */
-    analyze(): Promise<void>;
+    analyze(force?: boolean): Promise<void>;
     /**
      * Get the analyzed routes
      */
@@ -130,6 +140,10 @@ declare class RPCPlugin implements IPlugin {
      * Get the generation info
      */
     getGenerationInfo(): GeneratedClientInfo | null;
+    /**
+     * Checks whether expected output files exist on disk
+     */
+    private outputFilesExist;
     /**
      * Cleanup resources to prevent memory leaks
      */
@@ -184,26 +198,50 @@ declare class ClientGeneratorService {
     private analyzeRouteParameters;
 }
 
+interface ResolvedOpenApiOptions {
+    readonly title: string;
+    readonly version: string;
+    readonly description: string;
+    readonly servers: readonly {
+        url: string;
+        description?: string;
+    }[];
+    readonly outputFile: string;
+}
 /**
- * Service for analyzing controller methods and extracting type information
+ * Service for generating OpenAPI 3.0.3 specifications from analyzed routes and schemas
  */
-declare class RouteAnalyzerService {
-    private readonly controllerPattern;
-    private readonly tsConfigPath;
-    constructor(controllerPattern: string, tsConfigPath: string);
-    private projects;
+declare class OpenApiGeneratorService {
+    private readonly outputDir;
+    constructor(outputDir: string);
+    generateSpec(routes: readonly ExtendedRouteInfo[], schemas: readonly SchemaInfo[], options: ResolvedOpenApiOptions): Promise<string>;
+    private buildSpec;
+    private buildOperation;
+    private buildParameters;
+    private buildRequestBody;
+    private buildResponses;
+    private resolveResponseSchema;
+    private buildSchemaMap;
     /**
-     * Analyzes controller methods to extract type information
+     * Converts Express-style `:param` path to OpenAPI `{param}` syntax
      */
-    analyzeControllerMethods(): Promise<ExtendedRouteInfo[]>;
+    private toOpenApiPath;
+    private tsTypeToJsonSchema;
     /**
-     * Creates a new ts-morph project
+     * Extracts the base type name from a TS type string, stripping
+     * wrappers like `Partial<...>`, `...[]`, `Promise<...>`.
      */
-    private createProject;
+    private extractBaseTypeName;
+}
+
+/**
+ * Service for analyzing controller methods and extracting type information
+ */
+declare class RouteAnalyzerService {
     /**
-     * Cleanup resources to prevent memory leaks
+     * Analyzes controller methods to extract type information
      */
-    dispose(): void;
+    analyzeControllerMethods(project: Project): Promise<ExtendedRouteInfo[]>;
     /**
      * Finds controller classes in the project
      */
@@ -233,19 +271,10 @@ declare class SchemaGeneratorService {
     private readonly controllerPattern;
     private readonly tsConfigPath;
     constructor(controllerPattern: string, tsConfigPath: string);
-    private projects;
     /**
      * Generates JSON schemas from types used in controllers
      */
-    generateSchemas(): Promise<SchemaInfo[]>;
-    /**
-     * Creates a new ts-morph project
-     */
-    private createProject;
-    /**
-     * Cleanup resources to prevent memory leaks
-     */
-    dispose(): void;
+    generateSchemas(project: Project): Promise<SchemaInfo[]>;
     /**
      * Collects types from controller files
      */
@@ -264,6 +293,26 @@ declare class SchemaGeneratorService {
     private generateSchemaForType;
 }
 
+interface ChecksumData {
+    hash: string;
+    files: string[];
+}
+/**
+ * Computes a deterministic SHA-256 hash from file contents.
+ * Sorts paths before reading to ensure consistent ordering.
+ * Includes the file count in the hash so adding/removing files changes it.
+ */
+declare function computeHash(filePaths: string[]): string;
+/**
+ * Reads the stored checksum from the output directory.
+ * Returns null if the file is missing or corrupt.
+ */
+declare function readChecksum(outputDir: string): ChecksumData | null;
+/**
+ * Writes the checksum data to the output directory.
+ */
+declare function writeChecksum(outputDir: string, data: ChecksumData): Promise<void>;
+
 /**
  * Builds the full path with parameter placeholders
  */
@@ -295,10 +344,6 @@ declare function camelCase(str: string): string;
  * Extracts a named type from a TypeScript type
  */
 declare function extractNamedType(type: Type): string | null;
-/**
- * Generates type imports for the client
- */
-declare function generateTypeImports(routes: readonly any[]): string;
 
 /**
  * Default configuration options for the RPCPlugin
@@ -326,4 +371,4 @@ declare const BUILTIN_TYPES: Set<string>;
  */
 declare const GENERIC_TYPES: Set<string>;
 
-export { ApiError, BUILTIN_TYPES, BUILTIN_UTILITY_TYPES, 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, extractNamedType, generateTypeImports, generateTypeScriptInterface, mapJsonSchemaTypeToTypeScript, safeToString };
+export { ApiError, BUILTIN_TYPES, BUILTIN_UTILITY_TYPES, type ChecksumData, ClientGeneratorService, type ControllerGroups, DEFAULT_OPTIONS, type ExtendedRouteInfo, type FetchFunction, GENERIC_TYPES, type GeneratedClientInfo, LOG_PREFIX, OpenApiGeneratorService, type OpenApiOptions, type ParameterMetadataWithType, RPCPlugin, type RPCPluginOptions, type RequestOptions, RouteAnalyzerService, type RouteParameter, SchemaGeneratorService, type SchemaInfo, buildFullApiPath, buildFullPath, camelCase, computeHash, extractNamedType, generateTypeScriptInterface, mapJsonSchemaTypeToTypeScript, readChecksum, safeToString, writeChecksum };