@honestjs/rpc-plugin 1.2.0 → 1.3.0

package/dist/index.mjs

@@ -1,6 +1,7 @@
 // src/rpc.plugin.ts
-import fs2 from "fs";
-import path2 from "path";
+import fs3 from "fs";
+import path4 from "path";
+import { Project } from "ts-morph";
 
 // src/constants/defaults.ts
 var DEFAULT_OPTIONS = {
@@ -25,29 +26,66 @@ var BUILTIN_UTILITY_TYPES = /* @__PURE__ */ new Set([
 var BUILTIN_TYPES = /* @__PURE__ */ new Set(["string", "number", "boolean", "any", "void", "unknown"]);
 var GENERIC_TYPES = /* @__PURE__ */ new Set(["Array", "Promise", "Partial"]);
 
+// src/utils/hash-utils.ts
+import { createHash } from "crypto";
+import { existsSync, readFileSync } from "fs";
+import { mkdir, writeFile } from "fs/promises";
+import path from "path";
+var CHECKSUM_FILENAME = ".rpc-checksum";
+function computeHash(filePaths) {
+  const sorted = [...filePaths].sort();
+  const hasher = createHash("sha256");
+  hasher.update(`files:${sorted.length}
+`);
+  for (const filePath of sorted) {
+    hasher.update(readFileSync(filePath, "utf-8"));
+    hasher.update("\0");
+  }
+  return hasher.digest("hex");
+}
+function readChecksum(outputDir) {
+  const checksumPath = path.join(outputDir, CHECKSUM_FILENAME);
+  if (!existsSync(checksumPath)) return null;
+  try {
+    const raw = readFileSync(checksumPath, "utf-8");
+    const data = JSON.parse(raw);
+    if (typeof data.hash !== "string" || !Array.isArray(data.files)) {
+      return null;
+    }
+    return data;
+  } catch {
+    return null;
+  }
+}
+async function writeChecksum(outputDir, data) {
+  await mkdir(outputDir, { recursive: true });
+  const checksumPath = path.join(outputDir, CHECKSUM_FILENAME);
+  await writeFile(checksumPath, JSON.stringify(data, null, 2), "utf-8");
+}
+
 // src/services/client-generator.service.ts
 import fs from "fs/promises";
-import path from "path";
+import path2 from "path";
 
 // src/utils/path-utils.ts
 function buildFullPath(basePath, parameters) {
   if (!basePath || typeof basePath !== "string") return "/";
-  let path3 = basePath;
+  let path5 = basePath;
   if (parameters && Array.isArray(parameters)) {
     for (const param of parameters) {
       if (param.data && typeof param.data === "string" && param.data.startsWith(":")) {
         const paramName = param.data.slice(1);
-        path3 = path3.replace(`:${paramName}`, `\${${paramName}}`);
+        path5 = path5.replace(`:${paramName}`, `\${${paramName}}`);
       }
     }
   }
-  return path3;
+  return path5;
 }
 function buildFullApiPath(route) {
   const prefix = route.prefix || "";
   const version = route.version || "";
   const routePath = route.route || "";
-  const path3 = route.path || "";
+  const path5 = route.path || "";
   let fullPath = "";
   if (prefix && prefix !== "/") {
     fullPath += prefix.replace(/^\/+|\/+$/g, "");
@@ -58,11 +96,12 @@ function buildFullApiPath(route) {
   if (routePath && routePath !== "/") {
     fullPath += `/${routePath.replace(/^\/+|\/+$/g, "")}`;
   }
-  if (path3 && path3 !== "/") {
-    fullPath += `/${path3.replace(/^\/+|\/+$/g, "")}`;
-  } else if (path3 === "/") {
+  if (path5 && path5 !== "/") {
+    fullPath += `/${path5.replace(/^\/+|\/+$/g, "")}`;
+  } else if (path5 === "/") {
     fullPath += "/";
   }
+  if (fullPath && !fullPath.startsWith("/")) fullPath = "/" + fullPath;
   return fullPath || "/";
 }
 
@@ -88,7 +127,7 @@ var ClientGeneratorService = class {
     await fs.mkdir(this.outputDir, { recursive: true });
     await this.generateClientFile(routes, schemas);
     const generatedInfo = {
-      clientFile: path.join(this.outputDir, "client.ts"),
+      clientFile: path2.join(this.outputDir, "client.ts"),
       generatedAt: (/* @__PURE__ */ new Date()).toISOString()
     };
     return generatedInfo;
@@ -98,7 +137,7 @@ var ClientGeneratorService = class {
    */
   async generateClientFile(routes, schemas) {
     const clientContent = this.generateClientContent(routes, schemas);
-    const clientPath = path.join(this.outputDir, "client.ts");
+    const clientPath = path2.join(this.outputDir, "client.ts");
     await fs.writeFile(clientPath, clientContent, "utf-8");
   }
   /**
@@ -258,6 +297,14 @@ export class ApiClient {
 
 		try {
 			const response = await this.fetchFn(url.toString(), requestOptions)
+
+			if (response.status === 204 || response.headers.get('content-length') === '0') {
+				if (!response.ok) {
+					throw new ApiError(response.status, 'Request failed')
+				}
+				return undefined as T
+			}
+
 			const responseData = await response.json()
 
 			if (!response.ok) {
@@ -400,71 +447,216 @@ ${this.generateControllerMethods(controllerGroups)}
    */
   analyzeRouteParameters(route) {
     const parameters = route.parameters || [];
-    const method = String(route.method || "").toLowerCase();
-    const isInPath = (p) => {
-      const pathSegment = p.data;
-      return !!pathSegment && typeof pathSegment === "string" && route.path.includes(`:${pathSegment}`);
-    };
-    const pathParams = parameters.filter((p) => isInPath(p)).map((p) => ({ ...p, required: true }));
-    const rawBody = parameters.filter((p) => !isInPath(p) && method !== "get");
-    const bodyParams = rawBody.map((p) => ({
-      ...p,
-      required: true
-    }));
-    const queryParams = parameters.filter((p) => !isInPath(p) && method === "get").map((p) => ({
-      ...p,
-      required: p.required === true
-      // default false if not provided
-    }));
+    const pathParams = parameters.filter((p) => p.decoratorType === "param").map((p) => ({ ...p, required: true }));
+    const bodyParams = parameters.filter((p) => p.decoratorType === "body").map((p) => ({ ...p, required: true }));
+    const queryParams = parameters.filter((p) => p.decoratorType === "query").map((p) => ({ ...p, required: p.required === true }));
     return { pathParams, queryParams, bodyParams };
   }
 };
 
+// src/services/openapi-generator.service.ts
+import fs2 from "fs/promises";
+import path3 from "path";
+var OpenApiGeneratorService = class {
+  constructor(outputDir) {
+    this.outputDir = outputDir;
+  }
+  async generateSpec(routes, schemas, options) {
+    await fs2.mkdir(this.outputDir, { recursive: true });
+    const schemaMap = this.buildSchemaMap(schemas);
+    const spec = this.buildSpec(routes, schemaMap, options);
+    const outputPath = path3.join(this.outputDir, options.outputFile);
+    await fs2.writeFile(outputPath, JSON.stringify(spec, null, 2), "utf-8");
+    return outputPath;
+  }
+  buildSpec(routes, schemaMap, options) {
+    const spec = {
+      openapi: "3.0.3",
+      info: {
+        title: options.title,
+        version: options.version,
+        description: options.description
+      },
+      paths: {},
+      components: { schemas: schemaMap }
+    };
+    if (options.servers.length > 0) {
+      spec.servers = options.servers.map((s) => ({ ...s }));
+    }
+    for (const route of routes) {
+      const apiPath = this.toOpenApiPath(buildFullApiPath(route));
+      const method = safeToString(route.method).toLowerCase();
+      if (!spec.paths[apiPath]) {
+        spec.paths[apiPath] = {};
+      }
+      spec.paths[apiPath][method] = this.buildOperation(route, schemaMap);
+    }
+    return spec;
+  }
+  buildOperation(route, schemaMap) {
+    const controllerName = safeToString(route.controller).replace(/Controller$/, "");
+    const handlerName = safeToString(route.handler);
+    const parameters = route.parameters || [];
+    const operation = {
+      operationId: handlerName,
+      tags: [controllerName],
+      responses: this.buildResponses(route.returns, schemaMap)
+    };
+    const openApiParams = this.buildParameters(parameters);
+    if (openApiParams.length > 0) {
+      operation.parameters = openApiParams;
+    }
+    const requestBody = this.buildRequestBody(parameters, schemaMap);
+    if (requestBody) {
+      operation.requestBody = requestBody;
+    }
+    return operation;
+  }
+  buildParameters(parameters) {
+    const result = [];
+    for (const param of parameters) {
+      if (param.decoratorType === "param") {
+        result.push({
+          name: param.data ?? param.name,
+          in: "path",
+          required: true,
+          schema: this.tsTypeToJsonSchema(param.type)
+        });
+      } else if (param.decoratorType === "query") {
+        if (param.data) {
+          result.push({
+            name: param.data,
+            in: "query",
+            required: param.required === true,
+            schema: this.tsTypeToJsonSchema(param.type)
+          });
+        } else {
+          result.push({
+            name: param.name,
+            in: "query",
+            required: param.required === true,
+            schema: this.tsTypeToJsonSchema(param.type)
+          });
+        }
+      }
+    }
+    return result;
+  }
+  buildRequestBody(parameters, schemaMap) {
+    const bodyParams = parameters.filter((p) => p.decoratorType === "body");
+    if (bodyParams.length === 0) return null;
+    const bodyParam = bodyParams[0];
+    const typeName = this.extractBaseTypeName(bodyParam.type);
+    let schema;
+    if (typeName && schemaMap[typeName]) {
+      schema = { $ref: `#/components/schemas/${typeName}` };
+    } else {
+      schema = { type: "object" };
+    }
+    return {
+      required: true,
+      content: {
+        "application/json": { schema }
+      }
+    };
+  }
+  buildResponses(returns, schemaMap) {
+    const responseSchema = this.resolveResponseSchema(returns, schemaMap);
+    if (!responseSchema) {
+      return { "200": { description: "Successful response" } };
+    }
+    return {
+      "200": {
+        description: "Successful response",
+        content: {
+          "application/json": { schema: responseSchema }
+        }
+      }
+    };
+  }
+  resolveResponseSchema(returns, schemaMap) {
+    if (!returns) return null;
+    let innerType = returns;
+    const promiseMatch = returns.match(/^Promise<(.+)>$/);
+    if (promiseMatch) {
+      innerType = promiseMatch[1];
+    }
+    const isArray = innerType.endsWith("[]");
+    const baseType = isArray ? innerType.slice(0, -2) : innerType;
+    if (["string", "number", "boolean"].includes(baseType)) {
+      const primitiveSchema = this.tsTypeToJsonSchema(baseType);
+      return isArray ? { type: "array", items: primitiveSchema } : primitiveSchema;
+    }
+    if (["void", "any", "unknown"].includes(baseType)) return null;
+    if (schemaMap[baseType]) {
+      const ref = { $ref: `#/components/schemas/${baseType}` };
+      return isArray ? { type: "array", items: ref } : ref;
+    }
+    return null;
+  }
+  buildSchemaMap(schemas) {
+    const result = {};
+    for (const schemaInfo of schemas) {
+      const definition = schemaInfo.schema?.definitions?.[schemaInfo.type];
+      if (definition) {
+        result[schemaInfo.type] = definition;
+      }
+    }
+    return result;
+  }
+  /**
+   * Converts Express-style `:param` path to OpenAPI `{param}` syntax
+   */
+  toOpenApiPath(expressPath) {
+    return expressPath.replace(/:(\w+)/g, "{$1}");
+  }
+  tsTypeToJsonSchema(tsType) {
+    switch (tsType) {
+      case "number":
+        return { type: "number" };
+      case "boolean":
+        return { type: "boolean" };
+      case "string":
+      default:
+        return { type: "string" };
+    }
+  }
+  /**
+   * Extracts the base type name from a TS type string, stripping
+   * wrappers like `Partial<...>`, `...[]`, `Promise<...>`.
+   */
+  extractBaseTypeName(tsType) {
+    if (!tsType) return null;
+    let type = tsType;
+    const promiseMatch = type.match(/^Promise<(.+)>$/);
+    if (promiseMatch) type = promiseMatch[1];
+    type = type.replace(/\[\]$/, "");
+    const genericMatch = type.match(/^\w+<(\w+)>$/);
+    if (genericMatch) type = genericMatch[1];
+    if (["string", "number", "boolean", "any", "void", "unknown", "object"].includes(type)) {
+      return null;
+    }
+    return type;
+  }
+};
+
 // src/services/route-analyzer.service.ts
 import { RouteRegistry } from "honestjs";
-import { Project } from "ts-morph";
 var RouteAnalyzerService = class {
-  constructor(controllerPattern, tsConfigPath) {
-    this.controllerPattern = controllerPattern;
-    this.tsConfigPath = tsConfigPath;
-  }
-  // Track projects for cleanup
-  projects = [];
   /**
    * Analyzes controller methods to extract type information
    */
-  async analyzeControllerMethods() {
+  async analyzeControllerMethods(project) {
     const routes = RouteRegistry.getRoutes();
     if (!routes?.length) {
       return [];
     }
-    const project = this.createProject();
     const controllers = this.findControllerClasses(project);
     if (controllers.size === 0) {
       return [];
     }
     return this.processRoutes(routes, controllers);
   }
-  /**
-   * Creates a new ts-morph project
-   */
-  createProject() {
-    const project = new Project({
-      tsConfigFilePath: this.tsConfigPath
-    });
-    project.addSourceFilesAtPaths([this.controllerPattern]);
-    this.projects.push(project);
-    return project;
-  }
-  /**
-   * Cleanup resources to prevent memory leaks
-   */
-  dispose() {
-    this.projects.forEach((project) => {
-      project.getSourceFiles().forEach((file) => project.removeSourceFile(file));
-    });
-    this.projects = [];
-  }
   /**
    * Finds controller classes in the project
    */
@@ -487,23 +679,17 @@ var RouteAnalyzerService = class {
    */
   processRoutes(routes, controllers) {
     const analyzedRoutes = [];
-    const errors = [];
     for (const route of routes) {
       try {
         const extendedRoute = this.createExtendedRoute(route, controllers);
         analyzedRoutes.push(extendedRoute);
       } catch (routeError) {
-        const error = routeError instanceof Error ? routeError : new Error(String(routeError));
-        errors.push(error);
-        console.error(
-          `Error processing route ${safeToString(route.controller)}.${safeToString(route.handler)}:`,
+        console.warn(
+          `${LOG_PREFIX} Skipping route ${safeToString(route.controller)}.${safeToString(route.handler)}:`,
           routeError
         );
       }
     }
-    if (errors.length > 0) {
-      throw new Error(`Failed to process ${errors.length} routes: ${errors.map((e) => e.message).join(", ")}`);
-    }
     return analyzedRoutes;
   }
   /**
@@ -556,6 +742,7 @@ var RouteAnalyzerService = class {
     const sortedParams = [...parameters].sort((a, b) => a.index - b.index);
     for (const param of sortedParams) {
       const index = param.index;
+      const decoratorType = param.name;
       if (index < declaredParams.length) {
         const declaredParam = declaredParams[index];
         const paramName = declaredParam.getName();
@@ -563,6 +750,7 @@ var RouteAnalyzerService = class {
         result.push({
           index,
           name: paramName,
+          decoratorType,
           type: paramType,
           required: true,
           data: param.data,
@@ -573,6 +761,7 @@ var RouteAnalyzerService = class {
         result.push({
           index,
           name: `param${index}`,
+          decoratorType,
           type: param.metatype?.name || "unknown",
           required: true,
           data: param.data,
@@ -587,7 +776,6 @@ var RouteAnalyzerService = class {
 
 // src/services/schema-generator.service.ts
 import { createGenerator } from "ts-json-schema-generator";
-import { Project as Project2 } from "ts-morph";
 
 // src/utils/schema-utils.ts
 function mapJsonSchemaTypeToTypeScript(schema) {
@@ -654,32 +842,6 @@ function extractNamedType(type) {
   if (BUILTIN_TYPES.has(name)) return null;
   return name;
 }
-function generateTypeImports(routes) {
-  const types = /* @__PURE__ */ new Set();
-  for (const route of routes) {
-    if (route.parameters) {
-      for (const param of route.parameters) {
-        if (param.type && !["string", "number", "boolean"].includes(param.type)) {
-          const typeMatch = param.type.match(/(\w+)(?:<.*>)?/);
-          if (typeMatch) {
-            const typeName = typeMatch[1];
-            if (!BUILTIN_UTILITY_TYPES.has(typeName)) {
-              types.add(typeName);
-            }
-          }
-        }
-      }
-    }
-    if (route.returns) {
-      const returnType = route.returns.replace(/Promise<(.+)>/, "$1");
-      const baseType = returnType.replace(/\[\]$/, "");
-      if (!["string", "number", "boolean", "any", "void", "unknown"].includes(baseType)) {
-        types.add(baseType);
-      }
-    }
-  }
-  return Array.from(types).join(", ");
-}
 
 // src/services/schema-generator.service.ts
 var SchemaGeneratorService = class {
@@ -687,37 +849,14 @@ var SchemaGeneratorService = class {
     this.controllerPattern = controllerPattern;
     this.tsConfigPath = tsConfigPath;
   }
-  // Track projects for cleanup
-  projects = [];
   /**
    * Generates JSON schemas from types used in controllers
    */
-  async generateSchemas() {
-    const project = this.createProject();
+  async generateSchemas(project) {
     const sourceFiles = project.getSourceFiles(this.controllerPattern);
     const collectedTypes = this.collectTypesFromControllers(sourceFiles);
     return this.processTypes(collectedTypes);
   }
-  /**
-   * Creates a new ts-morph project
-   */
-  createProject() {
-    const project = new Project2({
-      tsConfigFilePath: this.tsConfigPath
-    });
-    project.addSourceFilesAtPaths([this.controllerPattern]);
-    this.projects.push(project);
-    return project;
-  }
-  /**
-   * Cleanup resources to prevent memory leaks
-   */
-  dispose() {
-    this.projects.forEach((project) => {
-      project.getSourceFiles().forEach((file) => project.removeSourceFile(file));
-    });
-    this.projects = [];
-  }
   /**
    * Collects types from controller files
    */
@@ -799,20 +938,37 @@ var RPCPlugin = class {
   routeAnalyzer;
   schemaGenerator;
   clientGenerator;
+  openApiGenerator;
+  openApiOptions;
+  // Shared ts-morph project
+  project = null;
   // Internal state
   analyzedRoutes = [];
   analyzedSchemas = [];
   generatedInfo = null;
   constructor(options = {}) {
     this.controllerPattern = options.controllerPattern ?? DEFAULT_OPTIONS.controllerPattern;
-    this.tsConfigPath = options.tsConfigPath ?? path2.resolve(process.cwd(), DEFAULT_OPTIONS.tsConfigPath);
-    this.outputDir = options.outputDir ?? path2.resolve(process.cwd(), DEFAULT_OPTIONS.outputDir);
+    this.tsConfigPath = options.tsConfigPath ?? path4.resolve(process.cwd(), DEFAULT_OPTIONS.tsConfigPath);
+    this.outputDir = options.outputDir ?? path4.resolve(process.cwd(), DEFAULT_OPTIONS.outputDir);
     this.generateOnInit = options.generateOnInit ?? DEFAULT_OPTIONS.generateOnInit;
-    this.routeAnalyzer = new RouteAnalyzerService(this.controllerPattern, this.tsConfigPath);
+    this.routeAnalyzer = new RouteAnalyzerService();
     this.schemaGenerator = new SchemaGeneratorService(this.controllerPattern, this.tsConfigPath);
     this.clientGenerator = new ClientGeneratorService(this.outputDir);
+    this.openApiOptions = this.resolveOpenApiOptions(options.openapi);
+    this.openApiGenerator = this.openApiOptions ? new OpenApiGeneratorService(this.outputDir) : null;
     this.validateConfiguration();
   }
+  resolveOpenApiOptions(input) {
+    if (!input) return null;
+    const opts = input === true ? {} : input;
+    return {
+      title: opts.title ?? "API",
+      version: opts.version ?? "1.0.0",
+      description: opts.description ?? "",
+      servers: opts.servers ?? [],
+      outputFile: opts.outputFile ?? "openapi.json"
+    };
+  }
   /**
    * Validates the plugin configuration
    */
@@ -824,7 +980,7 @@ var RPCPlugin = class {
     if (!this.tsConfigPath?.trim()) {
       errors.push("TypeScript config path cannot be empty");
     } else {
-      if (!fs2.existsSync(this.tsConfigPath)) {
+      if (!fs3.existsSync(this.tsConfigPath)) {
         errors.push(`TypeScript config file not found at: ${this.tsConfigPath}`);
       }
     }
@@ -849,15 +1005,37 @@ var RPCPlugin = class {
   /**
    * Main analysis method that coordinates all three components
    */
-  async analyzeEverything() {
+  async analyzeEverything(force = false) {
     try {
       this.log("Starting comprehensive RPC analysis...");
       this.analyzedRoutes = [];
       this.analyzedSchemas = [];
       this.generatedInfo = null;
-      this.analyzedRoutes = await this.routeAnalyzer.analyzeControllerMethods();
-      this.analyzedSchemas = await this.schemaGenerator.generateSchemas();
+      this.dispose();
+      this.project = new Project({ tsConfigFilePath: this.tsConfigPath });
+      this.project.addSourceFilesAtPaths([this.controllerPattern]);
+      const filePaths = this.project.getSourceFiles().map((f) => f.getFilePath());
+      if (!force) {
+        const currentHash = computeHash(filePaths);
+        const stored = readChecksum(this.outputDir);
+        if (stored && stored.hash === currentHash && this.outputFilesExist()) {
+          this.log("Source files unchanged \u2014 skipping regeneration");
+          this.dispose();
+          return;
+        }
+      }
+      this.analyzedRoutes = await this.routeAnalyzer.analyzeControllerMethods(this.project);
+      this.analyzedSchemas = await this.schemaGenerator.generateSchemas(this.project);
       this.generatedInfo = await this.clientGenerator.generateClient(this.analyzedRoutes, this.analyzedSchemas);
+      if (this.openApiGenerator && this.openApiOptions) {
+        const specPath = await this.openApiGenerator.generateSpec(
+          this.analyzedRoutes,
+          this.analyzedSchemas,
+          this.openApiOptions
+        );
+        this.log(`OpenAPI spec generated: ${specPath}`);
+      }
+      await writeChecksum(this.outputDir, { hash: computeHash(filePaths), files: filePaths });
       this.log(
         `\u2705 RPC analysis complete: ${this.analyzedRoutes.length} routes, ${this.analyzedSchemas.length} schemas`
       );
@@ -868,10 +1046,11 @@ var RPCPlugin = class {
     }
   }
   /**
-   * 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.
    */
-  async analyze() {
-    await this.analyzeEverything();
+  async analyze(force = true) {
+    await this.analyzeEverything(force);
   }
   /**
    * Get the analyzed routes
@@ -891,13 +1070,24 @@ var RPCPlugin = class {
   getGenerationInfo() {
     return this.generatedInfo;
   }
+  /**
+   * Checks whether expected output files exist on disk
+   */
+  outputFilesExist() {
+    if (!fs3.existsSync(path4.join(this.outputDir, "client.ts"))) return false;
+    if (this.openApiOptions) {
+      return fs3.existsSync(path4.join(this.outputDir, this.openApiOptions.outputFile));
+    }
+    return true;
+  }
   /**
    * Cleanup resources to prevent memory leaks
    */
   dispose() {
-    this.routeAnalyzer.dispose();
-    this.schemaGenerator.dispose();
-    this.log("Resources cleaned up");
+    if (this.project) {
+      this.project.getSourceFiles().forEach((file) => this.project.removeSourceFile(file));
+      this.project = null;
+    }
   }
   // ============================================================================
   // LOGGING UTILITIES
@@ -922,16 +1112,19 @@ export {
   DEFAULT_OPTIONS,
   GENERIC_TYPES,
   LOG_PREFIX,
+  OpenApiGeneratorService,
   RPCPlugin,
   RouteAnalyzerService,
   SchemaGeneratorService,
   buildFullApiPath,
   buildFullPath,
   camelCase,
+  computeHash,
   extractNamedType,
-  generateTypeImports,
   generateTypeScriptInterface,
   mapJsonSchemaTypeToTypeScript,
-  safeToString
+  readChecksum,
+  safeToString,
+  writeChecksum
 };
 //# sourceMappingURL=index.mjs.map