@honestjs/rpc-plugin 1.2.0 → 1.4.0

package/README.md

@@ -18,10 +18,13 @@ pnpm add @honestjs/rpc-plugin
 ```typescript
 import { RPCPlugin } from '@honestjs/rpc-plugin'
 import { Application } from 'honestjs'
+import AppModule from './app.module'
 
-const app = new Application({
-	plugins: [RPCPlugin]
+const { hono } = await Application.create(AppModule, {
+	plugins: [new RPCPlugin()]
 })
+
+export default hono
 ```
 
 ## Configuration Options
@@ -32,11 +35,46 @@ 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 context?: {
+		readonly namespace?: string // Default: 'rpc'
+		readonly keys?: {
+			readonly artifact?: string // Default: 'artifact'
+		}
+	}
+}
+```
+
+## Application Context Artifact
+
+After analysis, RPC plugin publishes this artifact to the application context:
+
+```typescript
+type RpcArtifact = {
+	routes: ExtendedRouteInfo[]
+	schemas: SchemaInfo[]
 }
 ```
 
+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'
+
+const { hono } = await Application.create(AppModule, {
+	plugins: [new RPCPlugin(), new ApiDocsPlugin({ artifact: 'rpc.artifact' })]
+})
+```
+
 ## 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                |
+| `.rpc-checksum` | Hash of source files for incremental caching | Always                |
+| `rpc-artifact.json` | Serialized routes/schemas artifact for cache-backed context publishing | Always |
+
 ### TypeScript RPC Client (`client.ts`)
 
 The plugin generates a single comprehensive file that includes both the client and all type definitions:
@@ -173,6 +211,27 @@ const testApiClient = new ApiClient('http://test.com', {
 expect(mockFetch).toHaveBeenCalledWith('http://test.com/api/v1/users/123', expect.objectContaining({ method: 'GET' }))
 ```
 
+## 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 +255,12 @@ 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. Incremental Caching
+
+- Hashes all matched controller files after glob resolution
+- Compares against the stored `.rpc-checksum`
+- Skips steps 1–3 when files are unchanged and output already exists
+
 ## Example Generated Output
 
 ### Generated Client
@@ -237,12 +302,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;
 });
 /**
@@ -86,6 +80,12 @@ interface RPCPluginOptions {
     readonly tsConfigPath?: string;
     readonly outputDir?: string;
     readonly generateOnInit?: boolean;
+    readonly context?: {
+        readonly namespace?: string;
+        readonly keys?: {
+            readonly artifact?: string;
+        };
+    };
 }
 /**
  * Comprehensive RPC plugin that combines route analysis, schema generation, and client generation
@@ -95,12 +95,16 @@ declare class RPCPlugin implements IPlugin {
     private readonly tsConfigPath;
     private readonly outputDir;
     private readonly generateOnInit;
+    private readonly contextNamespace;
+    private readonly contextArtifactKey;
     private readonly routeAnalyzer;
     private readonly schemaGenerator;
     private readonly clientGenerator;
+    private project;
     private analyzedRoutes;
     private analyzedSchemas;
     private generatedInfo;
+    private app;
     constructor(options?: RPCPluginOptions);
     /**
      * Validates the plugin configuration
@@ -115,9 +119,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 +135,15 @@ declare class RPCPlugin implements IPlugin {
      * Get the generation info
      */
     getGenerationInfo(): GeneratedClientInfo | null;
+    /**
+     * Checks whether expected output files exist on disk
+     */
+    private outputFilesExist;
+    private getArtifactPath;
+    private writeArtifactToDisk;
+    private loadArtifactFromDisk;
+    private publishArtifact;
+    private getArtifactContextKey;
     /**
      * Cleanup resources to prevent memory leaks
      */
@@ -188,22 +202,10 @@ declare class ClientGeneratorService {
  * Service for analyzing controller methods and extracting type information
  */
 declare class RouteAnalyzerService {
-    private readonly controllerPattern;
-    private readonly tsConfigPath;
-    constructor(controllerPattern: string, tsConfigPath: string);
-    private projects;
     /**
      * Analyzes controller methods to extract type information
      */
-    analyzeControllerMethods(): Promise<ExtendedRouteInfo[]>;
-    /**
-     * Creates a new ts-morph project
-     */
-    private createProject;
-    /**
-     * Cleanup resources to prevent memory leaks
-     */
-    dispose(): void;
+    analyzeControllerMethods(project: Project): Promise<ExtendedRouteInfo[]>;
     /**
      * Finds controller classes in the project
      */
@@ -233,19 +235,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 +257,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 +308,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
@@ -308,6 +317,12 @@ declare const DEFAULT_OPTIONS: {
     readonly tsConfigPath: "tsconfig.json";
     readonly outputDir: "./generated/rpc";
     readonly generateOnInit: true;
+    readonly context: {
+        readonly namespace: "rpc";
+        readonly keys: {
+            readonly artifact: "artifact";
+        };
+    };
 };
 /**
  * Log prefix for the RPC plugin
@@ -326,4 +341,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, 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;
 });
 /**
@@ -86,6 +80,12 @@ interface RPCPluginOptions {
     readonly tsConfigPath?: string;
     readonly outputDir?: string;
     readonly generateOnInit?: boolean;
+    readonly context?: {
+        readonly namespace?: string;
+        readonly keys?: {
+            readonly artifact?: string;
+        };
+    };
 }
 /**
  * Comprehensive RPC plugin that combines route analysis, schema generation, and client generation
@@ -95,12 +95,16 @@ declare class RPCPlugin implements IPlugin {
     private readonly tsConfigPath;
     private readonly outputDir;
     private readonly generateOnInit;
+    private readonly contextNamespace;
+    private readonly contextArtifactKey;
     private readonly routeAnalyzer;
     private readonly schemaGenerator;
     private readonly clientGenerator;
+    private project;
     private analyzedRoutes;
     private analyzedSchemas;
     private generatedInfo;
+    private app;
     constructor(options?: RPCPluginOptions);
     /**
      * Validates the plugin configuration
@@ -115,9 +119,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 +135,15 @@ declare class RPCPlugin implements IPlugin {
      * Get the generation info
      */
     getGenerationInfo(): GeneratedClientInfo | null;
+    /**
+     * Checks whether expected output files exist on disk
+     */
+    private outputFilesExist;
+    private getArtifactPath;
+    private writeArtifactToDisk;
+    private loadArtifactFromDisk;
+    private publishArtifact;
+    private getArtifactContextKey;
     /**
      * Cleanup resources to prevent memory leaks
      */
@@ -188,22 +202,10 @@ declare class ClientGeneratorService {
  * Service for analyzing controller methods and extracting type information
  */
 declare class RouteAnalyzerService {
-    private readonly controllerPattern;
-    private readonly tsConfigPath;
-    constructor(controllerPattern: string, tsConfigPath: string);
-    private projects;
     /**
      * Analyzes controller methods to extract type information
      */
-    analyzeControllerMethods(): Promise<ExtendedRouteInfo[]>;
-    /**
-     * Creates a new ts-morph project
-     */
-    private createProject;
-    /**
-     * Cleanup resources to prevent memory leaks
-     */
-    dispose(): void;
+    analyzeControllerMethods(project: Project): Promise<ExtendedRouteInfo[]>;
     /**
      * Finds controller classes in the project
      */
@@ -233,19 +235,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 +257,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 +308,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
@@ -308,6 +317,12 @@ declare const DEFAULT_OPTIONS: {
     readonly tsConfigPath: "tsconfig.json";
     readonly outputDir: "./generated/rpc";
     readonly generateOnInit: true;
+    readonly context: {
+        readonly namespace: "rpc";
+        readonly keys: {
+            readonly artifact: "artifact";
+        };
+    };
 };
 /**
  * Log prefix for the RPC plugin
@@ -326,4 +341,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, type ParameterMetadataWithType, RPCPlugin, type RPCPluginOptions, type RequestOptions, RouteAnalyzerService, type RouteParameter, SchemaGeneratorService, type SchemaInfo, buildFullApiPath, buildFullPath, camelCase, computeHash, extractNamedType, generateTypeScriptInterface, mapJsonSchemaTypeToTypeScript, readChecksum, safeToString, writeChecksum };