@bitstack/ng-query-codegen-openapi 0.0.30

package/src/services/unified-code-generator.ts

@@ -0,0 +1,353 @@
+import path from 'node:path';
+import ts from 'typescript';
+import type { OpenAPIV3 } from 'openapi-types';
+import { OpenApiService } from './openapi-service';
+import { GroupService, type GroupConfig } from './group-service';
+import { FileWriterService, type FileWriteResult } from './file-writer-service';
+export interface EndpointCacheKey {
+  operationName: string;
+  queryKeyName: string;
+  groupKey: string;
+}
+import { OpenApiParserService } from './openapi-parser-service';
+import { generateCacheKeysFile } from '../generators/cache-keys-generator';
+import { generateCommonTypesFile } from '../generators/common-types-generator';
+import { generateComponentSchemaFile } from '../generators/component-schema-generator';
+import { generateDoNotModifyFile } from '../generators/do-not-modify-generator';
+import type { GenerationOptions, CommonOptions } from '../types';
+import { ApiCodeGenerator } from './api-code-generator';
+import { generateUtilsFile } from '../generators/utils-generator';
+
+/**
+ * 統一代碼生成器選項
+ */
+export interface UnifiedGenerationOptions extends CommonOptions {
+  outputFiles: GroupConfig;
+  remoteFile?: string;
+}
+
+/**
+ * 統一代碼生成器結果
+ */
+export interface UnifiedGenerationResult {
+  success: boolean;
+  writtenFiles: FileWriteResult[];
+  errors: Error[];
+  generatedGroups: string[];
+}
+
+/**
+ * 統一代碼生成器
+ * 
+ * 設計理念：
+ * - 統一管理所有生成流程
+ * - 內建 schema 處理和存儲
+ * - 提供準備、生成、發佈的分階段操作
+ * - 避免重複初始化和處理
+ * 
+ * 使用方式：
+ * 1. prepare() - 準備階段：解析 schema、初始化服務
+ * 2. generateContent() - 生成階段：產生所有內容但不寫檔
+ * 3. release() - 發佈階段：統一寫入所有檔案
+ */
+export class UnifiedCodeGenerator {
+  private _options: UnifiedGenerationOptions;
+
+  private openApiService = new OpenApiService();
+  private groupService = new GroupService();
+  private fileWriterService = new FileWriterService();
+  
+  // 內部狀態存儲
+  private openApiDoc: OpenAPIV3.Document | null = null;
+  private parserService: OpenApiParserService | null = null;
+  private schemaInterfaces: Record<string, ts.InterfaceDeclaration | ts.TypeAliasDeclaration> = {};
+  private allEndpointCacheKeys: EndpointCacheKey[] = [];
+  private actualSchemaFile: string = '';
+  
+  // 生成內容存儲
+  private generatedContent: {
+    groups: Array<{
+      groupKey: string;
+      outputPath: string;
+      content: any;
+    }>;
+    cacheKeys: string | null;
+    commonTypes: string;
+    componentSchema: string;
+    doNotModify: string;
+    utils: string;
+  } = {
+    groups: [],
+    cacheKeys: null,
+    commonTypes: '',
+    componentSchema: '',
+    doNotModify: '',
+    utils: ''
+  };
+
+
+  constructor(options: UnifiedGenerationOptions) {
+    this._options = options;
+  }
+
+
+
+  /**
+   * 一次性生成（整合所有階段）
+   */
+  async generateAll(): Promise<UnifiedGenerationResult> {
+    await this.prepare();
+
+    // 生成各API文件
+    await this.generateApi();
+    // await this.generateQuery();
+
+    // 生成共用
+    this.generateCacheKeysContent()
+    this.generateCommonTypesContent()
+    this.generateSchemaContent()
+    this.generateUtilsContent()
+    this.generateDoNotModifyContent()
+
+    return await this.release();
+  }
+
+
+
+  /**
+   * 準備階段：解析 schema 並初始化所有服務
+   */
+  async prepare(): Promise<void> {
+    // console.log('UnifiedCodeGenerator: 準備階段開始...');
+    
+    // 步驟 1: 解析實際的 schema 檔案路徑
+    this.actualSchemaFile = this._options.schemaFile;
+    if (this._options.remoteFile) {
+      this.actualSchemaFile = await this.openApiService.downloadSchema(
+        this._options.remoteFile,
+        this._options.schemaFile
+      );
+    }
+
+    // 步驟 2: 獲取 OpenAPI 文檔（只初始化一次）
+    this.openApiDoc = await this.openApiService.getDocument(
+      this.actualSchemaFile,
+      this._options.httpResolverOptions
+    );
+
+    // 步驟 3: 初始化解析器服務並處理 schema
+    this.parserService = new OpenApiParserService(this.openApiDoc, this._options);
+    this.parserService.initialize();
+
+    // 步驟 4: 提取並儲存 schema interfaces
+    const apiGen = this.parserService.getApiGenerator();
+    this.schemaInterfaces = apiGen.aliases.reduce<Record<string, ts.InterfaceDeclaration | ts.TypeAliasDeclaration>>((curr, alias) => {
+      if (ts.isInterfaceDeclaration(alias) || ts.isTypeAliasDeclaration(alias)) {
+        const name = alias.name.text;
+        return {
+          ...curr,
+          [name]: alias,
+        };
+      }
+      return curr;
+    }, {});
+
+    // console.log('UnifiedCodeGenerator: 準備階段完成');
+  }
+
+
+
+  /**
+   * 生成階段：產生所有內容但不寫檔
+   */
+  async generateApi(): Promise<void> {
+    if (!this.openApiDoc || !this.parserService) {
+      throw new Error('請先調用 prepare() 方法');
+    }
+
+    // console.log('UnifiedCodeGenerator: 內容生成階段開始...');
+
+    // 獲取所有 API 接口Path並分組
+    const paths = this.openApiService.getPaths(this.openApiDoc);
+    const groupInfos = this.groupService.groupPaths(paths, this._options.outputFiles);
+
+    // 為每個群組生成內容
+    for (const groupInfo of Object.values(groupInfos)) {
+      try {
+        const groupContent = await this.generateApiGroupContent(
+          this._options,
+          groupInfo
+        );
+
+        // 檢查群組是否有任何有效的 endpoint
+        if (groupContent.operationNames.length > 0) {
+          this.generatedContent.groups.push({
+            groupKey: groupInfo.groupKey,
+            outputPath: groupInfo.outputPath,
+            content: groupContent
+          });
+        }
+        // 如果沒有任何 endpoint，則跳過此群組，不創建資料夾
+      } catch (error) {
+        throw new Error(`群組 ${groupInfo.groupKey} 生成失敗: ${error}`);
+      }
+    }
+
+    // console.log('UnifiedCodeGenerator: 內容生成階段完成');
+  }
+
+
+  /**
+   * 生成 cache keys
+   */
+  private async generateCacheKeysContent(): Promise<void> {
+    this.generatedContent.cacheKeys = generateCacheKeysFile(this.allEndpointCacheKeys);
+  }
+
+  /**
+   * 生成 common types
+   */
+  private async generateCommonTypesContent(): Promise<void> {
+    this.generatedContent.commonTypes = generateCommonTypesFile();
+  }
+
+  /**
+   * 生成Schema
+   */
+  private async generateSchemaContent(): Promise<void> {
+    this.generatedContent.componentSchema = generateComponentSchemaFile(this.schemaInterfaces);
+  }
+
+  /**
+   * 生成 DO_NOT_MODIFY.md
+   */
+  private async generateDoNotModifyContent(): Promise<void> {
+    this.generatedContent.doNotModify = generateDoNotModifyFile();
+  }
+
+
+  /**
+   * 生成 Utils Function
+   */
+  private async generateUtilsContent(): Promise<void> {
+    this.generatedContent.utils = generateUtilsFile();
+  }
+
+
+
+
+  /**
+   * 發佈階段：統一寫入所有檔案
+   */
+  async release(): Promise<UnifiedGenerationResult> {
+    const results: FileWriteResult[] = [];
+    const errors: Error[] = [];
+    const generatedGroups: string[] = [];
+
+    // console.log('UnifiedCodeGenerator: 發佈階段開始...');
+
+    try {
+      // 寫入群組檔案
+      for (const group of this.generatedContent.groups) {
+        try {
+          if (group.content?.files) {
+            const groupOutputDir = path.dirname(group.outputPath);
+            const groupResults = await this.fileWriterService.writeGroupFiles(
+              groupOutputDir,
+              {
+                types: group.content.files.types,
+                apiService: group.content.files.apiService,
+                queryService: group.content.files.queryService,
+                index: group.content.files.index
+              }
+            );
+            results.push(...groupResults);
+            generatedGroups.push(group.groupKey);
+          }
+        } catch (error) {
+          errors.push(new Error(`寫入群組 ${group.groupKey} 失敗: ${error}`));
+        }
+      }
+
+      // 寫入共用檔案
+      const outputDir = this.generatedContent.groups[0] ? 
+        path.dirname(path.dirname(this.generatedContent.groups[0].outputPath)) : 
+        './generated';
+
+      // 寫入共用檔案 (包含 DO_NOT_MODIFY.md)
+      if (this.generatedContent.cacheKeys || this.generatedContent.commonTypes || this.generatedContent.doNotModify || this.generatedContent.utils) {
+        const sharedResults = await this.fileWriterService.writeSharedFiles(
+          outputDir,
+          { 
+            cacheKeys: this.generatedContent.cacheKeys || undefined,
+            commonTypes: this.generatedContent.commonTypes || undefined,
+            doNotModify: this.generatedContent.doNotModify || undefined,
+            utils: this.generatedContent.utils || undefined
+          }
+        );
+        results.push(...sharedResults);
+      }
+
+      // 寫入 component schema
+      if (this.generatedContent.componentSchema) {
+        const schemaResults = await this.fileWriterService.writeSchemaFile(
+          outputDir,
+          this.generatedContent.componentSchema
+        );
+        results.push(...schemaResults);
+      }
+
+    } catch (error) {
+      errors.push(error as Error);
+    }
+
+    // console.log('UnifiedCodeGenerator: 發佈階段完成');
+
+    return {
+      success: errors.length === 0,
+      writtenFiles: results,
+      errors,
+      generatedGroups
+    };
+  }
+
+
+  /**
+   * 為單一群組生成內容
+   */
+  private async generateApiGroupContent(
+    options: UnifiedGenerationOptions,
+    groupInfo: { groupKey: string; paths: string[]; outputPath: string }
+  ): Promise<any> {
+    const { outputFiles, ...commonConfig } = options;
+
+    // 建立群組特定的生成選項
+    const groupOptions: GenerationOptions = {
+      ...commonConfig,
+      schemaFile: this.actualSchemaFile,
+      outputFile: groupInfo.outputPath,
+      sharedTypesFile: `${outputFiles.outputDir}/common-types.ts`,
+      filterEndpoints: this.groupService.createGroupFilter(groupInfo.groupKey, outputFiles),
+      queryMatch: outputFiles.queryMatch,
+      groupKey: groupInfo.groupKey,
+    };
+
+    // 使用新的 ApiCodeGenerator 生成程式碼，重用已處理的 v3Doc
+    if (!this.openApiDoc || !this.parserService) {
+      throw new Error('OpenAPI 文檔未初始化，請先調用 prepare()');
+    }
+    
+    const apiGenerator = new ApiCodeGenerator(this.parserService, groupOptions);
+    const result = await apiGenerator.generate();
+
+    // 提取並儲存快取鍵
+    if (result.files && 'allEndpointCacheKeys' in result.files) {
+      const cacheKeys = result.files.allEndpointCacheKeys as EndpointCacheKey[];
+      this.allEndpointCacheKeys.push(...cacheKeys);
+    }
+
+    return result;
+  }
+
+
+}

package/src/types.ts

@@ -0,0 +1,248 @@
+import type SwaggerParser from '@apidevtools/swagger-parser';
+import type { OpenAPIV3 } from 'openapi-types';
+import ts from 'typescript';
+
+// 重新匯出服務相關類型
+export type { 
+  GroupConfig,
+  GroupInfo 
+} from './services/group-service';
+
+export type { 
+  FileWriteResult 
+} from './services/file-writer-service';
+
+export type {
+  EndpointCacheKey
+} from './services/unified-code-generator';
+
+export type {
+  UnifiedGenerationOptions as EndpointGenerationOptions,
+  UnifiedGenerationResult as EndpointGenerationResult
+} from './services/unified-code-generator';
+
+export type OperationDefinition = {
+  path: string;
+  verb: (typeof operationKeys)[number];
+  pathItem: OpenAPIV3.PathItemObject;
+  operation: OpenAPIV3.OperationObject;
+};
+
+export type ParameterDefinition = OpenAPIV3.ParameterObject;
+
+type Require<T, K extends keyof T> = { [k in K]-?: NonNullable<T[k]> } & Omit<T, K>;
+type Optional<T, K extends keyof T> = { [k in K]?: NonNullable<T[k]> } & Omit<T, K>;
+type Id<T> = { [K in keyof T]: T[K] } & {};
+type AtLeastOneKey<T> = {
+  [K in keyof T]-?: Pick<T, K> & Partial<T>;
+}[keyof T];
+
+export const operationKeys = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'] as const;
+
+export type GenerationOptions = Id<
+  CommonOptions &
+    Optional<OutputFileOptions, 'outputFile'> & {
+      isDataResponse?(
+        code: string,
+        includeDefault: boolean,
+        response: OpenAPIV3.ResponseObject,
+        allResponses: OpenAPIV3.ResponsesObject
+      ): boolean;
+    }
+>;
+
+export interface CommonOptions {
+  /**
+   * local schema file path (only supports local files)
+   */
+  schemaFile: string;
+  /**
+   * remote schema file URL (when provided, will download to schemaFile path)
+   */
+  remoteFile?: string;
+  /**
+   * Configuration for WebApiConfiguration import
+   * defaults to { file: "@core/api/web-api-configuration", importName: "WebApiConfiguration" }
+   */
+  apiConfiguration?: {
+    file: string;
+    importName: string;
+  };
+  /**
+   * HttpClient for WebApiConfiguration import
+   * defaults to { file: "@core/httpClient/webapi/webapi-http-client.providers", importName: "WEBAPI_HTTP_CLIENT" }
+   */
+  httpClient?: {
+    file: string;
+    importName: string;
+  };
+  /**
+   * defaults to "enhancedApi"
+   */
+  exportName?: string;
+  /**
+   * defaults to "Req"
+   */
+  argSuffix?: string;
+  /**
+   * defaults to "Res"
+   */
+  responseSuffix?: string;
+  /**
+   * defaults to empty
+   */
+  operationNameSuffix?: string;
+  /**
+   * defaults to `false`
+   * `true` will generate hooks for queries and mutations, but no lazyQueries
+   */
+  hooks?: boolean | { queries: boolean; lazyQueries: boolean; mutations: boolean };
+  /**
+   * defaults to false
+   * `true` will generate a union type for `undefined` properties like: `{ id?: string | undefined }` instead of `{ id?: string }`
+   */
+  unionUndefined?: boolean;
+  /**
+   * defaults to false
+   * `true` will result in all generated endpoints having `providesTags`/`invalidatesTags` declarations for the `tags` of their respective operation definition
+   * @see https://redux-toolkit.js.org/rtk-query/usage/code-generation for more information
+   */
+  tag?: boolean;
+  /**
+   * defaults to false
+   * `true` will add `encodeURIComponent` to the generated path parameters
+   */
+  encodePathParams?: boolean;
+  /**
+   * defaults to false
+   * `true` will add `encodeURIComponent` to the generated query parameters
+   */
+  encodeQueryParams?: boolean;
+  /**
+   * defaults to false
+   * `true` will "flatten" the arg so that you can do things like `useGetEntityById(1)` instead of `useGetEntityById({ entityId: 1 })`
+   */
+  flattenArg?: boolean;
+  /**
+   * default to false
+   * If set to `true`, the default response type will be included in the generated code for all endpoints.
+   * @see https://swagger.io/docs/specification/describing-responses/#default
+   */
+  includeDefault?: boolean;
+  /**
+   * default to false
+   * `true` will not generate separate types for read-only and write-only properties.
+   */
+  mergeReadWriteOnly?: boolean;
+  /**
+   *
+   * HTTPResolverOptions object that is passed to the SwaggerParser bundle function.
+   */
+  httpResolverOptions?: SwaggerParser.HTTPResolverOptions;
+
+  /**
+   * defaults to undefined
+   * If present the given file will be used as prettier config when formatting the generated code. If undefined the default prettier config
+   * resolution mechanism will be used.
+   */
+  prettierConfigFile?: string;
+  /**
+   * defaults to "@acrool/react-fetcher"
+   * File path for importing IRestFulEndpointsQueryReturn type
+   */
+  endpointsQueryReturnTypeFile?: string;
+  /**
+   * defaults to 60 (seconds)
+   * Number of seconds to wait before refetching data when component mounts or args change
+   */
+  refetchOnMountOrArgChange?: number;
+}
+
+export type TextMatcher = string | RegExp | (string | RegExp)[];
+
+export type EndpointMatcherFunction = (operationName: string, operationDefinition: OperationDefinition) => boolean;
+
+export type EndpointMatcher = TextMatcher | EndpointMatcherFunction;
+
+export type ParameterMatcherFunction = (parameterName: string, parameterDefinition: ParameterDefinition) => boolean;
+
+export type ParameterMatcher = TextMatcher | ParameterMatcherFunction;
+
+export interface OutputFileOptions extends Partial<CommonOptions> {
+  outputFile: string;
+  filterEndpoints?: EndpointMatcher;
+  endpointOverrides?: EndpointOverrides[];
+  queryMatch?: (method: string, path: string) => boolean;
+  /**
+   * defaults to false
+   * If passed as true it will generate TS enums instead of union of strings
+   */
+  useEnumType?: boolean;
+  sharedTypesFile?: string;
+  /**
+   * groupKey for service class naming, e.g., "room" -> "RoomService"
+   */
+  groupKey?: string;
+}
+
+export type EndpointOverrides = {
+  pattern: EndpointMatcher;
+} & AtLeastOneKey<{
+  type: 'mutation' | 'query';
+  parameterFilter: ParameterMatcher;
+}>;
+
+export type OutputFilesConfig = {
+  groupKeyMatch: (path: string) => string;
+  outputDir: string;
+  queryMatch?: (method: string, path: string) => boolean;
+  filterEndpoint?: (operationName: string, path: string, groupKey: string) => boolean;
+};
+
+export type ConfigFile =
+  | Id<Require<CommonOptions & OutputFileOptions, 'outputFile'>>
+  | Id<
+      Omit<CommonOptions, 'outputFile'> & {
+        // outputFiles: { [outputFile: string]: Omit<OutputFileOptions, 'outputFile'> };
+        outputFiles: OutputFilesConfig
+      }
+    >;
+
+export type GenerateApiResult = {
+  operationNames: string[];
+  files: {
+    types: string;
+    apiService: string;
+    queryService: string;
+    index: string;
+    commonTypes?: string;
+    cacheKeys?: string;
+    componentSchema?: string;
+    allEndpointCacheKeys?: Array<{
+      operationName: string
+      queryKeyName: string
+      groupKey: string
+    }>;
+  };
+};
+
+
+
+export type QueryArgDefinition = {
+  name: string;
+  originalName: string;
+  type: ts.TypeNode;
+  required?: boolean;
+  param?: OpenAPIV3.ParameterObject;
+} & (
+  | {
+  origin: 'param';
+  param: OpenAPIV3.ParameterObject;
+}
+  | {
+  origin: 'body';
+  body: OpenAPIV3.RequestBodyObject;
+}
+  );
+
+export type QueryArgDefinitions = Record<string, QueryArgDefinition>;

package/src/utils/capitalize.ts

@@ -0,0 +1,3 @@
+export function capitalize(str: string) {
+  return str.replace(str[0], str[0].toUpperCase());
+}

package/src/utils/directory.ts

@@ -0,0 +1,75 @@
+import path from 'node:path';
+import fs from 'node:fs';
+
+/**
+ * 確保目錄存在的函數
+ * @param filePath
+ */
+export async function ensureDirectoryExists(filePath: string) {
+  const dirname = path.dirname(filePath);
+  if (!fs.existsSync(dirname)) {
+    await fs.promises.mkdir(dirname, { recursive: true });
+  }
+}
+
+/**
+ * 檢查檔案是否存在的函數
+ * @param filePath
+ */
+export function fileExists(filePath: string): boolean {
+  try {
+    return fs.statSync(filePath).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 獲取資料夾名稱並轉換為 API 名稱
+ * @param dirPath
+ */
+export function getApiNameFromDir(dirPath: string): string {
+  const dirName = path.basename(dirPath);
+  return `${dirName}Api`;
+}
+
+
+
+
+/**
+ * 確保基礎文件存在的函數
+ * @param outputDir
+ * @param operationNames
+ */
+export async function ensureBaseFilesExist(outputDir: string, operationNames: string[]) {
+  const enhanceEndpointsPath = path.join(outputDir, 'enhanceEndpoints.ts');
+  const indexPath = path.join(outputDir, 'index.ts');
+
+  // 如果 enhanceEndpoints.ts 不存在，創建它
+  if (!fileExists(enhanceEndpointsPath)) {
+    // 生成操作名稱的字符串
+    const operationNamesString = operationNames
+      .map(name => `        ${name}: {},`)
+      .join('\n');
+
+    const enhanceEndpointsContent = `import api from './query.service';
+
+const enhancedApi = api.enhanceEndpoints({
+    endpoints: {
+${operationNamesString}
+    },
+});
+
+export default enhancedApi;
+`;
+    await fs.promises.writeFile(enhanceEndpointsPath, enhanceEndpointsContent, 'utf-8');
+  }
+  // 如果文件已存在，不做任何修改
+
+  // 如果 index.ts 不存在，創建它
+  if (!fileExists(indexPath)) {
+    const indexContent = `export * from './query.service';
+`;
+    await fs.promises.writeFile(indexPath, indexContent, 'utf-8');
+  }
+}

package/src/utils/downloadSchema.ts

@@ -0,0 +1,33 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { isValidUrl } from './isValidUrl';
+
+export async function downloadSchemaFile(remoteFile: string, targetPath: string): Promise<string> {
+  // 如果不是網址，拋出錯誤
+  if (!isValidUrl(remoteFile)) {
+    throw new Error(`remoteFile must be a valid URL: ${remoteFile}`);
+  }
+
+  try {
+    // 確保目錄存在
+    const dir = path.dirname(targetPath);
+    if (!fs.existsSync(dir)) {
+      await fs.promises.mkdir(dir, { recursive: true });
+    }
+
+    // 下載檔案
+    const response = await fetch(remoteFile);
+    if (!response.ok) {
+      throw new Error(`Failed to download schema from ${remoteFile}: ${response.statusText}`);
+    }
+
+    const content = await response.text();
+    await fs.promises.writeFile(targetPath, content, 'utf-8');
+
+    console.log(`Schema downloaded from ${remoteFile} to ${targetPath}`);
+    return targetPath;
+  } catch (error) {
+    console.error(`Error downloading schema from ${remoteFile}:`, error);
+    throw error;
+  }
+}