openapi-sync 2.1.10 → 2.1.11

package/README.md

@@ -37,7 +37,9 @@
 - Customizable naming conventions for types and endpoints
 - Exclude/include endpoints by exact path or regex patterns
 - Tag-based filtering, method-specific filtering, and pattern matching
-- Flexible output directory structure
+- Folder splitting configuration for organized code generation
+- OperationId-based naming for better type and endpoint names
+- Flexible output directory structure with custom folder organization
 - URL transformation and text replacement rules
 - Configurable documentation generation
 - Support for multiple API specifications
@@ -153,6 +155,18 @@ const config: IConfig = {
   },
   server: "https://api.example.com", // Override server URL
 
+  // NEW: Folder splitting configuration
+  folderSplit: {
+    byTags: true, // Create folders based on endpoint tags
+    customFolder: ({ method, path, tags, operationId }) => {
+      // Custom logic to determine folder structure
+      if (tags?.includes("admin")) return "admin";
+      if (tags?.includes("public")) return "public";
+      if (path.startsWith("/api/v1/")) return "v1";
+      return null; // Use default folder structure
+    },
+  },
+
   // Type generation configuration
   types: {
     name: {
@@ -247,6 +261,7 @@ export default config;
 | `folder`          | `string`                 | Output directory for generated files          | `""`     |
 | `api`             | `Record<string, string>` | Map of API names to OpenAPI spec URLs         | Required |
 | `server`          | `number \| string`       | Server index or custom server URL             | `0`      |
+| `folderSplit`     | `IConfigFolderSplit`     | Configuration for folder splitting            | -        |
 
 #### Type Configuration (`types`)
 
@@ -284,6 +299,44 @@ If `operationId` is not available, the system falls back to the default path-bas
 | `include.tags`        | `string[]`                                                | Include endpoints by tags                                 |
 | `include.endpoints`   | `Array<{path?: string, regex?: string, method?: Method}>` | Include specific endpoints by exact path or regex pattern |
 
+#### Folder Splitting Configuration (`folderSplit`)
+
+| Property       | Type       | Description                                   |
+| -------------- | ---------- | --------------------------------------------- |
+| `byTags`       | `boolean`  | Create folders based on endpoint tags         |
+| `customFolder` | `function` | Custom function to determine folder structure |
+
+**Folder Splitting Examples:**
+
+```typescript
+// Split by tags - creates folders like "admin/", "public/", "user/"
+folderSplit: {
+  byTags: true,
+}
+
+// Custom folder logic
+folderSplit: {
+  customFolder: ({ method, path, tags, operationId }) => {
+    // Admin endpoints go to admin folder
+    if (tags?.includes("admin")) return "admin";
+
+    // Public endpoints go to public folder
+    if (tags?.includes("public")) return "public";
+
+    // API versioning
+    if (path.startsWith("/api/v1/")) return "v1";
+    if (path.startsWith("/api/v2/")) return "v2";
+
+    // Method-based organization
+      const method = data.method.toLowerCase();
+    if (method === "get") return "read";
+    if (method === "post" || method === "PUT") return "write";
+
+    return null; // Use default structure
+  },
+}
+```
+
 ## Usage
 
 ### CLI Usage
@@ -378,6 +431,8 @@ export default (): IConfig => {
 
 OpenAPI Sync generates a structured output in your specified folder:
 
+### Default Structure
+
 ```
 src/api/
 ├── petstore/
@@ -392,6 +447,37 @@ src/api/
         └── shared.ts
 ```
 
+### Folder Splitting Structure
+
+When `folderSplit.byTags` is enabled or custom folder logic is used:
+
+```
+src/api/
+├── petstore/
+│   ├── admin/                # Endpoints with "admin" tag
+│   │   ├── endpoints.ts
+│   │   └── types/
+│   │       ├── index.ts
+│   │       └── shared.ts
+│   ├── public/               # Endpoints with "public" tag
+│   │   ├── endpoints.ts
+│   │   └── types/
+│   │       ├── index.ts
+│   │       └── shared.ts
+│   └── user/                 # Endpoints with "user" tag
+│       ├── endpoints.ts
+│       └── types/
+│           ├── index.ts
+│           └── shared.ts
+└── auth-api/
+    ├── v1/                   # Custom folder logic
+    │   ├── endpoints.ts
+    │   └── types/
+    └── v2/
+        ├── endpoints.ts
+        └── types/
+```
+
 ### Generated Endpoints
 
 When `endpoints.value.type` is set to `"string"`
@@ -565,6 +651,93 @@ import {
 
 ## Advanced Examples
 
+### Advanced Folder Splitting Configuration
+
+```typescript
+// openapi.sync.ts
+import { IConfig } from "openapi-sync/types";
+
+const config: IConfig = {
+  refetchInterval: 5000,
+  folder: "./src/api",
+  api: {
+    "main-api": "https://api.example.com/openapi.json",
+  },
+
+  // Advanced folder splitting with multiple strategies
+  folderSplit: {
+    byTags: true, // Enable tag-based splitting
+    customFolder: ({ method, path, tags, operationId }) => {
+      // Priority-based folder assignment
+
+      // 1. Admin endpoints always go to admin folder
+      if (tags?.includes("admin")) return "admin";
+
+      // 2. Public API endpoints
+      if (tags?.includes("public")) return "public";
+
+      // 3. Version-based splitting
+      if (path.startsWith("/api/v1/")) return "v1";
+      if (path.startsWith("/api/v2/")) return "v2";
+
+      // 4. Method-based organization for remaining endpoints
+      if (method === "GET") return "read";
+      if (method === "POST" || method === "PUT" || method === "PATCH")
+        return "write";
+      if (method === "DELETE") return "delete";
+
+      // 5. OperationId-based splitting for specific operations
+      if (operationId?.includes("Auth")) return "auth";
+      if (operationId?.includes("User")) return "user";
+
+      return null; // Use default structure
+    },
+  },
+
+  // Enhanced type naming with operationId support
+  types: {
+    name: {
+      prefix: "I",
+      useOperationId: true, // Use operationId when available
+      format: (source, data, defaultName) => {
+        if (source === "endpoint" && data.operationId) {
+          // Use operationId for better naming
+          switch (data.type) {
+            case "query":
+              return `${data.operationId}Query`;
+            case "dto":
+              return `${data.operationId}DTO`;
+            case "response":
+              return `${data.operationId}${data.code}Response`;
+          }
+        }
+        return defaultName;
+      },
+    },
+  },
+
+  // Enhanced endpoint configuration
+  endpoints: {
+    name: {
+      useOperationId: true, // Use operationId for endpoint names
+      format: ({ operationId, method, path }, defaultName) => {
+        if (operationId) return operationId;
+        return defaultName;
+      },
+    },
+    exclude: {
+      tags: ["deprecated", "internal"],
+      endpoints: [
+        { regex: "^/internal/.*" },
+        { path: "/debug", method: "GET" },
+      ],
+    },
+  },
+};
+
+export default config;
+```
+
 ### Multi-Environment Configuration
 
 ```typescript
@@ -989,6 +1162,34 @@ The tool maintains state in `db.json` to track changes:
 
 ---
 
+## Changelog
+
+### v2.1.11 (Latest)
+
+- **NEW**: Folder splitting configuration for organized code generation
+  - `folderSplit.byTags` - Create folders based on endpoint tags
+  - `folderSplit.customFolder` - Custom function for folder structure logic
+- Enhanced folder organization with priority-based assignment
+- Improved code organization for large APIs
+
+### v2.1.10
+
+- OperationId-based naming for types and endpoints
+  - `types.name.useOperationId` - Use OpenAPI operationId for type naming
+  - `endpoints.name.useOperationId` - Use operationId for endpoint naming
+- Enhanced endpoint filtering capabilities
+  - Improved tag-based filtering
+  - Better regex pattern matching
+  - More flexible include/exclude rules
+- Enhanced JSONStringify function with array serialization support
+- Improved endpoint tags support in generated documentation
+
+### Previous Versions
+
+- v2.1.9: Enhanced JSONStringify function improvements
+- v2.1.8: File extension corrections and path handling
+- v2.1.7: Endpoint tags support in API documentation
+
 ## License
 
 This project is licensed under the ISC License - see the [LICENSE](LICENSE) file for details.

package/dist/{types.d.ts → index.d.mts}

@@ -1,6 +1,7 @@
-import { Method } from "axios";
-export type IOpenApiSpec = Record<"openapi", string> & Record<string, any>;
-export type IOpenApSchemaSpec = {
+import { Method } from 'axios';
+
+type IOpenApiSpec = Record<"openapi", string> & Record<string, any>;
+type IOpenApSchemaSpec = {
     nullable?: boolean;
     type: "string" | "integer" | "number" | "array" | "object" | "boolean" | "null" | any[];
     example?: any;
@@ -16,7 +17,7 @@ export type IOpenApSchemaSpec = {
     oneOf?: IOpenApSchemaSpec[];
     allOf?: IOpenApSchemaSpec[];
 };
-export type IOpenApiParameterSpec = {
+type IOpenApiParameterSpec = {
     $ref?: string;
     name: string;
     in: string;
@@ -32,28 +33,28 @@ export type IOpenApiParameterSpec = {
     example?: any;
     examples?: any[];
 };
-export type IOpenApiMediaTypeSpec = {
+type IOpenApiMediaTypeSpec = {
     schema?: IOpenApSchemaSpec;
     example?: any;
     examples?: any[];
     encoding?: any;
 };
-export type IOpenApiRequestBodySpec = {
+type IOpenApiRequestBodySpec = {
     description?: string;
     required?: boolean;
     content: Record<string, IOpenApiMediaTypeSpec>;
 };
-export type IOpenApiResponseSpec = Record<string, IOpenApiRequestBodySpec>;
-export type IConfigReplaceWord = {
+type IOpenApiResponseSpec = Record<string, IOpenApiRequestBodySpec>;
+type IConfigReplaceWord = {
     /**  string and regular expression as a string*/
     replace: string;
     with: string;
 };
-export type IConfigDoc = {
+type IConfigDoc = {
     disable?: boolean;
     showCurl?: boolean;
 };
-export type IConfigExclude = {
+type IConfigExclude = {
     /** Exclude/Include endpoints by tags */
     tags?: string[];
     /** Exclude/Include individual endpoints by path and method */
@@ -66,13 +67,30 @@ export type IConfigExclude = {
         method?: Method;
     }>;
 };
-export interface IConfigInclude extends IConfigExclude {
+interface IConfigInclude extends IConfigExclude {
 }
-export type IConfig = {
+type IConfigFolderSplit = {
+    /** Split folders by tags - creates folders named after each tag */
+    byTags?: boolean;
+    /** Custom function to determine folder name for each endpoint */
+    customFolder?: (data: {
+        method: Method;
+        path: string;
+        summary?: string;
+        operationId?: string;
+        tags?: string[];
+        parameters?: IOpenApiParameterSpec[];
+        requestBody?: IOpenApiRequestBodySpec;
+        responses?: IOpenApiResponseSpec;
+    }) => string | null;
+};
+type IConfig = {
     refetchInterval?: number;
     folder?: string;
     api: Record<string, string>;
     server?: number | string;
+    /** Configuration for splitting generated code into folders */
+    folderSplit?: IConfigFolderSplit;
     /** Configuration for excluding endpoints from code generation */
     types?: {
         name?: {
@@ -111,7 +129,7 @@ export type IConfig = {
         include?: IConfigInclude;
     };
 };
-export type IOpenApiSecuritySchemes = {
+type IOpenApiSecuritySchemes = {
     [key: string]: {
         type: "http" | "apiKey" | "oauth2" | "openIdConnect" | "mutualTLS";
         scheme?: "bearer" | "basic";
@@ -130,3 +148,25 @@ export type IOpenApiSecuritySchemes = {
         name?: string;
     };
 };
+
+declare const isJson: (value: any) => boolean;
+declare const isYamlString: (fileContent: string) => boolean;
+declare const yamlStringToJson: (fileContent: string) => any;
+declare const capitalize: (text: string) => string;
+declare const getEndpointDetails: (path: string, method: string) => {
+    name: string;
+    variables: string[];
+    pathParts: string[];
+};
+declare const JSONStringify: (obj: Record<string, any>, indent?: number) => string;
+declare const renderTypeRefMD: (typeRef: string, indent?: number) => string;
+declare function getNestedValue<T>(obj: object, path: string): T | undefined;
+
+declare const variableName: RegExp;
+declare const variableNameChar: RegExp;
+
+declare const Init: (options?: {
+    refetchInterval?: number;
+}) => Promise<void>;
+
+export { type IConfig, type IConfigDoc, type IConfigExclude, type IConfigFolderSplit, type IConfigInclude, type IConfigReplaceWord, type IOpenApSchemaSpec, type IOpenApiMediaTypeSpec, type IOpenApiParameterSpec, type IOpenApiRequestBodySpec, type IOpenApiResponseSpec, type IOpenApiSecuritySchemes, type IOpenApiSpec, Init, JSONStringify, capitalize, getEndpointDetails, getNestedValue, isJson, isYamlString, renderTypeRefMD, variableName, variableNameChar, yamlStringToJson };

package/dist/index.d.ts

@@ -1,6 +1,172 @@
-export * from "./types";
-export * from "./helpers";
-export * from "./regex";
-export declare const Init: (options?: {
+import { Method } from 'axios';
+
+type IOpenApiSpec = Record<"openapi", string> & Record<string, any>;
+type IOpenApSchemaSpec = {
+    nullable?: boolean;
+    type: "string" | "integer" | "number" | "array" | "object" | "boolean" | "null" | any[];
+    example?: any;
+    enum?: string[];
+    format?: string;
+    items?: IOpenApSchemaSpec;
+    required?: string[];
+    description?: string;
+    $ref?: string;
+    properties?: Record<string, IOpenApSchemaSpec>;
+    additionalProperties?: IOpenApSchemaSpec;
+    anyOf?: IOpenApSchemaSpec[];
+    oneOf?: IOpenApSchemaSpec[];
+    allOf?: IOpenApSchemaSpec[];
+};
+type IOpenApiParameterSpec = {
+    $ref?: string;
+    name: string;
+    in: string;
+    enum?: string[];
+    description?: string;
+    required?: boolean;
+    deprecated?: boolean;
+    allowEmptyValue?: boolean;
+    style?: string;
+    explode?: boolean;
+    allowReserved?: boolean;
+    schema?: IOpenApSchemaSpec;
+    example?: any;
+    examples?: any[];
+};
+type IOpenApiMediaTypeSpec = {
+    schema?: IOpenApSchemaSpec;
+    example?: any;
+    examples?: any[];
+    encoding?: any;
+};
+type IOpenApiRequestBodySpec = {
+    description?: string;
+    required?: boolean;
+    content: Record<string, IOpenApiMediaTypeSpec>;
+};
+type IOpenApiResponseSpec = Record<string, IOpenApiRequestBodySpec>;
+type IConfigReplaceWord = {
+    /**  string and regular expression as a string*/
+    replace: string;
+    with: string;
+};
+type IConfigDoc = {
+    disable?: boolean;
+    showCurl?: boolean;
+};
+type IConfigExclude = {
+    /** Exclude/Include endpoints by tags */
+    tags?: string[];
+    /** Exclude/Include individual endpoints by path and method */
+    endpoints?: Array<{
+        /** Exact path match (regex will be ignore when provided)*/
+        path?: string;
+        /** Regular expression pattern for path matching */
+        regex?: string;
+        /** Don't specify method to exclude all methods */
+        method?: Method;
+    }>;
+};
+interface IConfigInclude extends IConfigExclude {
+}
+type IConfigFolderSplit = {
+    /** Split folders by tags - creates folders named after each tag */
+    byTags?: boolean;
+    /** Custom function to determine folder name for each endpoint */
+    customFolder?: (data: {
+        method: Method;
+        path: string;
+        summary?: string;
+        operationId?: string;
+        tags?: string[];
+        parameters?: IOpenApiParameterSpec[];
+        requestBody?: IOpenApiRequestBodySpec;
+        responses?: IOpenApiResponseSpec;
+    }) => string | null;
+};
+type IConfig = {
+    refetchInterval?: number;
+    folder?: string;
+    api: Record<string, string>;
+    server?: number | string;
+    /** Configuration for splitting generated code into folders */
+    folderSplit?: IConfigFolderSplit;
+    /** Configuration for excluding endpoints from code generation */
+    types?: {
+        name?: {
+            prefix?: string;
+            useOperationId?: boolean;
+            format?: (source: "shared" | "endpoint", data: {
+                name?: string;
+                type?: "response" | "dto" | "query";
+                code?: string;
+                method?: Method;
+                path?: string;
+                summary?: string;
+                operationId?: string;
+            }, defaultName: string) => string | null | undefined;
+        };
+        doc?: IConfigDoc;
+    };
+    endpoints?: {
+        value?: {
+            replaceWords?: IConfigReplaceWord[];
+            includeServer?: boolean;
+            type?: "string" | "object";
+        };
+        name?: {
+            format?: (data: {
+                method: Method;
+                path: string;
+                summary: string;
+                operationId: string;
+            }, defaultName: string) => string | null;
+            prefix?: string;
+            useOperationId?: boolean;
+        };
+        doc?: IConfigDoc;
+        exclude?: IConfigExclude;
+        include?: IConfigInclude;
+    };
+};
+type IOpenApiSecuritySchemes = {
+    [key: string]: {
+        type: "http" | "apiKey" | "oauth2" | "openIdConnect" | "mutualTLS";
+        scheme?: "bearer" | "basic";
+        in?: "query" | "header" | "cookie";
+        flows?: {
+            authorizationCode: {
+                authorizationUrl: "https://example.com/auth";
+                tokenUrl: "https://example.com/token";
+                scopes: {
+                    "read:data": "Grants read access";
+                };
+            };
+        };
+        bearerFormat?: "JWT";
+        openIdConnectUrl?: string;
+        name?: string;
+    };
+};
+
+declare const isJson: (value: any) => boolean;
+declare const isYamlString: (fileContent: string) => boolean;
+declare const yamlStringToJson: (fileContent: string) => any;
+declare const capitalize: (text: string) => string;
+declare const getEndpointDetails: (path: string, method: string) => {
+    name: string;
+    variables: string[];
+    pathParts: string[];
+};
+declare const JSONStringify: (obj: Record<string, any>, indent?: number) => string;
+declare const renderTypeRefMD: (typeRef: string, indent?: number) => string;
+declare function getNestedValue<T>(obj: object, path: string): T | undefined;
+
+declare const variableName: RegExp;
+declare const variableNameChar: RegExp;
+
+declare const Init: (options?: {
     refetchInterval?: number;
 }) => Promise<void>;
+
+export { type IConfig, type IConfigDoc, type IConfigExclude, type IConfigFolderSplit, type IConfigInclude, type IConfigReplaceWord, type IOpenApSchemaSpec, type IOpenApiMediaTypeSpec, type IOpenApiParameterSpec, type IOpenApiRequestBodySpec, type IOpenApiResponseSpec, type IOpenApiSecuritySchemes, type IOpenApiSpec, Init, JSONStringify, capitalize, getEndpointDetails, getNestedValue, isJson, isYamlString, renderTypeRefMD, variableName, variableNameChar, yamlStringToJson };