@honestjs/rpc-plugin 1.3.0 → 1.4.1

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,18 +35,36 @@ 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)
+	readonly context?: {
+		readonly namespace?: string // Default: 'rpc'
+		readonly keys?: {
+			readonly artifact?: string // Default: 'artifact'
+		}
+	}
 }
+```
+
+## Application Context Artifact
 
-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')
+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`):
@@ -51,8 +72,8 @@ 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                |
+| `rpc-artifact.json` | Serialized routes/schemas artifact for cache-backed context publishing | Always |
 
 ### TypeScript RPC Client (`client.ts`)
 
@@ -190,46 +211,6 @@ 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.
@@ -274,18 +255,11 @@ You can also delete `.rpc-checksum` from the output directory to clear the cache
 - 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
+### 4. 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
+- Skips steps 1–3 when files are unchanged and output already exists
 
 ## Example Generated Output
 

package/dist/index.d.mts

@@ -72,16 +72,6 @@ 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
  */
@@ -90,7 +80,12 @@ interface RPCPluginOptions {
     readonly tsConfigPath?: string;
     readonly outputDir?: string;
     readonly generateOnInit?: boolean;
-    readonly openapi?: OpenApiOptions | boolean;
+    readonly context?: {
+        readonly namespace?: string;
+        readonly keys?: {
+            readonly artifact?: string;
+        };
+    };
 }
 /**
  * Comprehensive RPC plugin that combines route analysis, schema generation, and client generation
@@ -100,17 +95,17 @@ 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 readonly openApiGenerator;
-    private readonly openApiOptions;
     private project;
     private analyzedRoutes;
     private analyzedSchemas;
     private generatedInfo;
+    private app;
     constructor(options?: RPCPluginOptions);
-    private resolveOpenApiOptions;
     /**
      * Validates the plugin configuration
      */
@@ -144,6 +139,11 @@ declare class RPCPlugin implements IPlugin {
      * 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
      */
@@ -198,42 +198,6 @@ 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 generating OpenAPI 3.0.3 specifications from analyzed routes and schemas
- */
-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;
-    /**
-     * Converts Express-style `:param` path to OpenAPI `{param}` syntax
-     */
-    private toOpenApiPath;
-    private tsTypeToJsonSchema;
-    /**
-     * Extracts the base type name from a TS type string, stripping
-     * wrappers like `Partial<...>`, `...[]`, `Promise<...>`.
-     */
-    private extractBaseTypeName;
-}
-
 /**
  * Service for analyzing controller methods and extracting type information
  */
@@ -313,6 +277,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
  */
@@ -320,7 +286,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
@@ -353,6 +319,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
@@ -371,4 +343,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, 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 };
+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 };

package/dist/index.d.ts

@@ -72,16 +72,6 @@ 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
  */
@@ -90,7 +80,12 @@ interface RPCPluginOptions {
     readonly tsConfigPath?: string;
     readonly outputDir?: string;
     readonly generateOnInit?: boolean;
-    readonly openapi?: OpenApiOptions | boolean;
+    readonly context?: {
+        readonly namespace?: string;
+        readonly keys?: {
+            readonly artifact?: string;
+        };
+    };
 }
 /**
  * Comprehensive RPC plugin that combines route analysis, schema generation, and client generation
@@ -100,17 +95,17 @@ 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 readonly openApiGenerator;
-    private readonly openApiOptions;
     private project;
     private analyzedRoutes;
     private analyzedSchemas;
     private generatedInfo;
+    private app;
     constructor(options?: RPCPluginOptions);
-    private resolveOpenApiOptions;
     /**
      * Validates the plugin configuration
      */
@@ -144,6 +139,11 @@ declare class RPCPlugin implements IPlugin {
      * 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
      */
@@ -198,42 +198,6 @@ 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 generating OpenAPI 3.0.3 specifications from analyzed routes and schemas
- */
-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;
-    /**
-     * Converts Express-style `:param` path to OpenAPI `{param}` syntax
-     */
-    private toOpenApiPath;
-    private tsTypeToJsonSchema;
-    /**
-     * Extracts the base type name from a TS type string, stripping
-     * wrappers like `Partial<...>`, `...[]`, `Promise<...>`.
-     */
-    private extractBaseTypeName;
-}
-
 /**
  * Service for analyzing controller methods and extracting type information
  */
@@ -313,6 +277,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
  */
@@ -320,7 +286,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
@@ -353,6 +319,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
@@ -371,4 +343,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, 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 };
+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 };