@honestjs/rpc-plugin 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Orkhan Karimov <karimovok1@gmail.com> (https://github.com/kerimovok)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,219 @@
+# @honestjs/rpc-plugin
+
+A comprehensive RPC plugin for HonestJS that combines route analysis, schema generation, and client generation into a
+single, tightly-coupled solution.
+
+## Features
+
+- **Route Analysis**: Automatically analyzes controller methods and extracts type information using ts-morph
+- **Schema Generation**: Generates JSON schemas and TypeScript interfaces from types used in controllers
+- **Client Generation**: Creates a fully-typed TypeScript RPC client with proper parameter typing
+- **Tight Integration**: All components share data directly, eliminating duplication and file I/O overhead
+- **Type Safety**: Full TypeScript support with generated types and interfaces
+
+## Installation
+
+```bash
+npm install @honestjs/rpc-plugin
+# or
+yarn add @honestjs/rpc-plugin
+# or
+pnpm add @honestjs/rpc-plugin
+```
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { RPCPlugin } from '@honestjs/rpc-plugin'
+import { Application } from 'honestjs'
+
+const app = new Application({
+	plugins: [
+		new RPCPlugin({
+			outputDir: './generated/rpc'
+		})
+	]
+})
+```
+
+### Configuration Options
+
+```typescript
+interface RPCPluginOptions {
+	readonly controllerPattern?: string // Glob pattern for controller files (default: 'src/modules/*/*.controller.ts')
+	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)
+}
+```
+
+## What It Generates
+
+### 1. TypeScript RPC Client (`client.ts`)
+
+A fully-typed client that provides:
+
+- **Controller-based organization**: Methods grouped by controller
+- **Type-safe parameters**: Path, query, and body parameters with proper typing
+- **Flexible request options**: Clean separation of params, query, body, and headers
+- **Error handling**: Built-in error handling with custom ApiError class
+- **Authentication support**: Easy header and auth token management
+
+```typescript
+// Generated client usage
+import { ApiClient } from './generated/rpc/client'
+
+// Create client instance with base URL
+const apiClient = new ApiClient('http://localhost:3000')
+
+// Type-safe API calls
+const user = await apiClient.users.create({
+	body: { name: 'John', email: 'john@example.com' }
+})
+
+const users = await apiClient.users.list({
+	query: { page: 1, limit: 10 }
+})
+
+const user = await apiClient.users.getById({
+	params: { id: '123' }
+})
+
+// Set default authentication
+apiClient.setDefaultAuth('your-jwt-token')
+
+// Set custom headers
+apiClient.setDefaultHeaders({
+	'X-API-Key': 'your-api-key'
+})
+```
+
+### 2. Type Definitions (`types.ts`)
+
+Comprehensive type definitions including:
+
+- **Generated DTOs**: TypeScript interfaces from your controller types
+- **Route information**: Complete route metadata with parameter types
+- **API response types**: Standardized response and error types
+- **Utility types**: Request options and parameter types
+
+## How It Works
+
+### 1. Route Analysis
+
+- Scans your HonestJS route registry
+- Uses ts-morph to analyze controller source code
+- Extracts method signatures, parameter types, and return types
+- Builds comprehensive route metadata
+
+### 2. Schema Generation
+
+- Analyzes types used in controller methods
+- Generates JSON schemas using ts-json-schema-generator
+- Creates TypeScript interfaces from schemas
+- Integrates with route analysis for complete type coverage
+
+### 3. Client Generation
+
+- Groups routes by controller for organization
+- Generates type-safe method signatures
+- Creates parameter validation and typing
+- Builds the complete RPC client with proper error handling
+
+## Benefits of the Unified Approach
+
+- **No Duplication**: Single source of truth for all type information
+- **Tight Coupling**: Components share data directly without file I/O
+- **Better Performance**: Eliminates redundant analysis and file generation
+- **Consistent Types**: All generated code uses the same type definitions
+- **Easier Maintenance**: Single plugin to configure and maintain
+
+## Example Generated Output
+
+### Route Analysis
+
+```typescript
+export interface ExtendedRouteInfo {
+	controller: string
+	handler: string
+	method: string
+	path: string
+	fullPath: string
+	returns?: string
+	parameters?: ParameterMetadataWithType[]
+}
+
+export const ANALYZED_ROUTES = [
+	{
+		controller: 'UsersController',
+		handler: 'create',
+		method: 'POST',
+		path: '/',
+		fullPath: '/api/v1/users/',
+		returns: 'Promise<User>',
+		parameters: [
+			{
+				index: 0,
+				name: 'createUserDto',
+				type: 'CreateUserDto',
+				required: true,
+				data: undefined
+			}
+		]
+	}
+] as const
+```
+
+### Generated Client
+
+```typescript
+export class ApiClient {
+	get users() {
+		return {
+			create: async (
+				options: RequestOptions<{ name: string; email: string }, undefined, undefined, undefined>
+			): Promise<ApiResponse<any>> => {
+				return this.request('POST', `/api/v1/users/`, options)
+			},
+			list: async (
+				options?: RequestOptions<undefined, { page: number; limit: number }, undefined, undefined>
+			): Promise<ApiResponse<any>> => {
+				return this.request('GET', `/api/v1/users/`, options)
+			}
+		}
+	}
+}
+
+// RequestOptions type definition
+export type RequestOptions<
+	TParams = undefined,
+	TQuery = undefined,
+	TBody = undefined,
+	THeaders = undefined
+> = (TParams extends undefined ? object : { params: TParams }) &
+	(TQuery extends undefined ? object : { query: TQuery }) &
+	(TBody extends undefined ? object : { body: TBody }) &
+	(THeaders extends undefined ? object : { headers: THeaders })
+```
+
+## Plugin Lifecycle
+
+The plugin automatically generates files when your HonestJS application starts up (if `generateOnInit` is true). You can
+also manually trigger generation:
+
+```typescript
+const rpcPlugin = new RPCPlugin()
+await rpcPlugin.analyze() // Manually trigger analysis and generation
+```
+
+## Dependencies
+
+- **ts-morph**: TypeScript source code analysis
+- **ts-json-schema-generator**: JSON schema generation from TypeScript types
+- **honestjs**: Core framework integration
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,337 @@
+import { RouteInfo, ParameterMetadata, IPlugin, Application } from 'honestjs';
+import { Hono } from 'hono';
+import { Type } from 'ts-morph';
+
+/**
+ * Parameter metadata with enhanced type information
+ */
+interface ParameterMetadataWithType extends ParameterMetadata {
+    readonly type: string;
+    readonly required: boolean;
+    readonly name: string;
+}
+/**
+ * Extended route information with comprehensive type data
+ */
+interface ExtendedRouteInfo extends Omit<RouteInfo, 'parameters' | 'method'> {
+    readonly returns?: string;
+    readonly parameters?: readonly ParameterMetadataWithType[];
+    readonly method: string;
+    readonly fullPath: string;
+}
+/**
+ * Controller groups for organization
+ */
+type ControllerGroups = Map<string, readonly ExtendedRouteInfo[]>;
+/**
+ * Route parameter information for client generation
+ * Extends ParameterMetadataWithType for consistency
+ */
+interface RouteParameter extends ParameterMetadataWithType {
+}
+
+/**
+ * Schema with comprehensive type information
+ */
+interface SchemaInfo {
+    readonly type: string;
+    readonly schema: Record<string, any>;
+    readonly typescriptType?: string;
+}
+/**
+ * Generated client file information
+ */
+interface GeneratedClientInfo {
+    readonly clientFile: string;
+    readonly generatedAt: string;
+}
+
+/**
+ * Clean separation of concerns for request options
+ */
+type RequestOptions<TParams = never, TQuery = never, TBody = never, THeaders = never> = (TParams extends never ? {
+    params?: never;
+} : {
+    params: TParams;
+}) & (TQuery extends never ? {
+    query?: never;
+} : {
+    query?: TQuery;
+}) & (TBody extends never ? {
+    body?: never;
+} : {
+    body: TBody;
+}) & (THeaders extends never ? {
+    headers?: never;
+} : {
+    headers: THeaders;
+});
+/**
+ * API Response wrapper
+ */
+interface ApiResponse<T = any> {
+    data: T;
+    message?: string;
+    success: boolean;
+}
+/**
+ * API Error class
+ */
+declare class ApiError extends Error {
+    statusCode: number;
+    constructor(statusCode: number, message: string);
+}
+
+/**
+ * Configuration options for the RPCPlugin
+ */
+interface RPCPluginOptions {
+    readonly controllerPattern?: string;
+    readonly tsConfigPath?: string;
+    readonly outputDir?: string;
+    readonly generateOnInit?: boolean;
+}
+/**
+ * Comprehensive RPC plugin that combines route analysis, schema generation, and client generation
+ */
+declare class RPCPlugin implements IPlugin {
+    private readonly controllerPattern;
+    private readonly tsConfigPath;
+    private readonly outputDir;
+    private readonly generateOnInit;
+    private readonly routeAnalyzer;
+    private readonly schemaGenerator;
+    private readonly clientGenerator;
+    private readonly analyzedRoutes;
+    private readonly analyzedSchemas;
+    private generatedInfo;
+    constructor(options?: RPCPluginOptions);
+    /**
+     * Validates the plugin configuration
+     */
+    private validateConfiguration;
+    /**
+     * Called after all modules are registered
+     */
+    afterModulesRegistered: (app: Application, hono: Hono) => Promise<void>;
+    /**
+     * Main analysis method that coordinates all three components
+     */
+    private analyzeEverything;
+    /**
+     * Manually trigger analysis (useful for testing or re-generation)
+     */
+    analyze(): Promise<void>;
+    /**
+     * Get the analyzed routes
+     */
+    getRoutes(): readonly ExtendedRouteInfo[];
+    /**
+     * Get the analyzed schemas
+     */
+    getSchemas(): readonly SchemaInfo[];
+    /**
+     * Get the generation info
+     */
+    getGenerationInfo(): GeneratedClientInfo | null;
+    /**
+     * Cleanup resources to prevent memory leaks
+     */
+    dispose(): void;
+    /**
+     * Plugin lifecycle cleanup
+     */
+    onDestroy(): void;
+    /**
+     * Logs a message with the plugin prefix
+     */
+    private log;
+    /**
+     * Logs an error with the plugin prefix
+     */
+    private logError;
+}
+
+/**
+ * Service for generating TypeScript RPC clients
+ */
+declare class ClientGeneratorService {
+    private readonly outputDir;
+    constructor(outputDir: string);
+    /**
+     * Generates the TypeScript RPC client
+     */
+    generateClient(routes: readonly ExtendedRouteInfo[], schemas: readonly SchemaInfo[]): Promise<GeneratedClientInfo>;
+    /**
+     * Generates the main client file with types included
+     */
+    private generateClientFile;
+    /**
+     * Generates the client TypeScript content with types included
+     */
+    private generateClientContent;
+    /**
+     * Generates controller methods for the client
+     */
+    private generateControllerMethods;
+    /**
+     * Extracts the proper return type from route analysis
+     */
+    private extractReturnType;
+    /**
+     * 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
+     */
+    private analyzeRouteParameters;
+}
+
+/**
+ * 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;
+    /**
+     * Finds controller classes in the project
+     */
+    private findControllerClasses;
+    /**
+     * Processes all routes and extracts type information
+     */
+    private processRoutes;
+    /**
+     * Creates an extended route with type information
+     */
+    private createExtendedRoute;
+    /**
+     * Gets the return type of a method
+     */
+    private getReturnType;
+    /**
+     * Gets parameters with their types
+     */
+    private getParametersWithTypes;
+}
+
+/**
+ * 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 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;
+    /**
+     * Collects types from controller files
+     */
+    private collectTypesFromControllers;
+    /**
+     * Collects types from a single method
+     */
+    private collectTypesFromMethod;
+    /**
+     * Processes collected types to generate schemas
+     */
+    private processTypes;
+    /**
+     * Generates schema for a specific type
+     */
+    private generateSchemaForType;
+}
+
+/**
+ * Builds the full path with parameter placeholders
+ */
+declare function buildFullPath(basePath: string, parameters: readonly ParameterMetadata[]): string;
+/**
+ * Builds the full API path using route information
+ */
+declare function buildFullApiPath(route: ExtendedRouteInfo): string;
+
+/**
+ * Maps JSON schema types to TypeScript types
+ */
+declare function mapJsonSchemaTypeToTypeScript(schema: Record<string, any>): string;
+/**
+ * Generates TypeScript interface from JSON schema
+ */
+declare function generateTypeScriptInterface(typeName: string, schema: Record<string, any>): string;
+
+/**
+ * Safely converts a value to string, handling symbols and other types
+ */
+declare function safeToString(value: unknown): string;
+/**
+ * Converts a string to camelCase
+ */
+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
+ */
+declare const DEFAULT_OPTIONS: {
+    readonly controllerPattern: "src/modules/*/*.controller.ts";
+    readonly tsConfigPath: "tsconfig.json";
+    readonly outputDir: "./generated/rpc";
+    readonly generateOnInit: true;
+};
+/**
+ * Log prefix for the RPC plugin
+ */
+declare const LOG_PREFIX = "[ RPCPlugin ]";
+/**
+ * Built-in TypeScript types that should not be imported
+ */
+declare const BUILTIN_UTILITY_TYPES: Set<string>;
+/**
+ * Built-in TypeScript types that should be skipped
+ */
+declare const BUILTIN_TYPES: Set<string>;
+/**
+ * Generic type names that should be unwrapped
+ */
+declare const GENERIC_TYPES: Set<string>;
+
+export { ApiError, type ApiResponse, BUILTIN_TYPES, BUILTIN_UTILITY_TYPES, ClientGeneratorService, type ControllerGroups, DEFAULT_OPTIONS, type ExtendedRouteInfo, 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 };