klasik 1.0.17 → 1.0.20

package/README.md

@@ -9,6 +9,7 @@ Download OpenAPI specifications from remote URLs and generate TypeScript clients
 - 📄 **JSON and YAML support** - Automatically parse and handle both formats (YAML specs are converted to JSON for code generation)
 - 🔐 **Authentication support** - Custom headers including Bearer tokens and API keys
 - 🔗 **External reference resolution** - Automatically download referenced schema files (`$ref`)
+- 📦 **ESM compatibility** - Automatic `.js` extension fixing for Node.js ESM projects
 - 🔄 **Automatic transformation** - Converts API responses to class instances using class-transformer
 - 🎯 **Type-safe** - Full TypeScript support with decorators
 - 🛠️ **Configurable** - Custom headers, timeouts, and templates
@@ -95,10 +96,14 @@ Generate a TypeScript client from an OpenAPI spec (remote URL or local file).
 - `-u, --url <url>` - URL or file path to the OpenAPI spec (required)
   - Supports: `https://...`, `http://...`, `file://...`, `/absolute/path`, `./relative/path`
 - `-o, --output <dir>` - Output directory for generated client code (required)
+- `-m, --mode <mode>` - Generation mode: `full` (models + APIs + config) or `models-only` (default: `full`)
+  - `full`: Generates complete axios client with APIs, models, and configuration
+  - `models-only`: Generates only model classes with class-transformer decorators (no API client code)
 - `-H, --header <header...>` - Custom headers for HTTP requests (format: "Key: Value")
   - Can be used multiple times for multiple headers
   - Perfect for authorization: `--header "Authorization: Bearer token"`
 - `-r, --resolve-refs` - Resolve and download external `$ref` references
+- `--esm` - Add `.js` extensions to imports for ESM compatibility (Node.js modules)
 - `-t, --template <dir>` - Custom template directory (klasik includes enhanced TSDoc templates by default)
 - `-k, --keep-spec` - Keep the downloaded spec file after generation
 - `--timeout <ms>` - Request timeout in milliseconds for HTTP requests (default: 30000)
@@ -417,6 +422,127 @@ await new K8sClientGenerator().generate({
 });
 ```
 
+## Best Practices for Existing Projects
+
+When integrating klasik into an existing TypeScript project, follow these best practices to avoid conflicts:
+
+### Generate into a Subdirectory
+
+```bash
+# Generate models into src/generated to avoid overwriting project files
+npx klasik generate \
+  --url https://api.example.com/openapi.yaml \
+  --output ./src/generated \
+  --mode models-only \
+  --resolve-refs
+```
+
+### Clean Up Generated Config Files
+
+klasik generates `package.json` and `tsconfig.json` files. Remove them after generation:
+
+```json
+// package.json
+{
+  "scripts": {
+    "generate-client": "npx klasik generate --url $API_URL --output ./src/generated --mode models-only --resolve-refs && npm run cleanup-generated",
+    "cleanup-generated": "rm -f ./src/generated/package.json ./src/generated/tsconfig*.json ./src/generated/.openapi-generator*"
+  }
+}
+```
+
+### TypeScript Configuration for class-transformer
+
+Add these settings to your `tsconfig.json` for compatibility:
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "skipLibCheck": true  // Skip type checking in node_modules (recommended for class-transformer)
+  }
+}
+```
+
+### Models-Only Mode
+
+Use `--mode models-only` when you:
+- Only need data models with class-transformer decorators
+- Want to use your own API client (axios, fetch, etc.)
+- Are integrating into an existing project with its own HTTP layer
+- Want to avoid package.json/tsconfig.json conflicts
+
+```bash
+npx klasik generate \
+  --url https://api.example.com/openapi.yaml \
+  --output ./src/generated \
+  --mode models-only  # ✅ Generates only models, no API client
+```
+
+### Full Mode
+
+Use `--mode full` (default) when you:
+- Want a complete ready-to-use axios client
+- Are starting a new project from scratch
+- Want automatic response transformation with class-transformer
+
+```bash
+npx klasik generate \
+  --url https://api.example.com/openapi.yaml \
+  --output ./api-client \
+  --mode full  # Generates complete client with APIs
+```
+
+### ESM (ECMAScript Modules) Support
+
+If your project uses ECMAScript Modules (`"type": "module"` in package.json), use the `--esm` flag to automatically add `.js` extensions to all relative imports:
+
+```bash
+# Generate ESM-compatible code
+npx klasik generate \
+  --url https://api.example.com/openapi.yaml \
+  --output ./src/generated \
+  --mode models-only \
+  --esm  # ✅ Adds .js extensions to imports
+```
+
+**What `--esm` does:**
+- Adds `.js` extensions to all relative imports: `from './user'` → `from './user.js'`
+- Adds `.js` extensions to all relative exports: `export * from './api'` → `export * from './api.js'`
+- Handles directory imports: `from './models'` → `from './models/index.js'`
+- Only affects relative imports (doesn't touch external packages like `axios`, `class-transformer`)
+
+**Before `--esm`:**
+```typescript
+import { User } from './models/user';
+import { Cluster } from '../models/cluster';
+export * from './api/orgs-api';
+```
+
+**After `--esm`:**
+```typescript
+import { User } from './models/user.js';
+import { Cluster } from '../models/cluster.js';
+export * from './api/orgs-api.js';
+```
+
+**When to use `--esm`:**
+- Your package.json has `"type": "module"`
+- You're using Node.js native ESM
+- You're targeting modern JavaScript environments
+- You want to eliminate post-processing scripts
+
+**package.json setup for ESM:**
+```json
+{
+  "type": "module",
+  "scripts": {
+    "generate-client": "npx klasik generate --url $API_URL --output src/generated --mode models-only --esm"
+  }
+}
+```
+
 ## Advanced Configuration
 
 ### Custom Error Handling

package/dist/cli.js

@@ -52,6 +52,7 @@ program
     .option('-t, --template <dir>', 'Custom template directory')
     .option('-k, --keep-spec', 'Keep the downloaded spec file after generation', false)
     .option('-r, --resolve-refs', 'Resolve and download external $ref references', false)
+    .option('--esm', 'Add .js extensions to imports for ESM compatibility', false)
     .option('--timeout <ms>', 'Request timeout in milliseconds', '30000')
     .action(async (options) => {
     try {
@@ -82,6 +83,7 @@ program
             templateDir: options.template,
             keepSpec: options.keepSpec,
             resolveReferences: options.resolveRefs,
+            fixEsmImports: options.esm,
             timeout: parseInt(options.timeout, 10),
         });
         process.exit(0);

package/dist/esm-fixer.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Fixes relative imports in TypeScript files to include .js extensions for ESM compatibility
+ *
+ * Node.js ESM requires explicit file extensions for relative imports.
+ * This utility adds .js extensions to all relative import/export statements.
+ */
+export declare class EsmFixer {
+    /**
+     * Fix all TypeScript files in a directory recursively
+     */
+    fixDirectory(directory: string): Promise<void>;
+    /**
+     * Fix imports in a single file
+     * @returns true if file was modified, false otherwise
+     */
+    private fixFile;
+    /**
+     * Fix import statements to add .js extensions
+     */
+    private fixImports;
+    /**
+     * Fix export statements to add .js extensions
+     */
+    private fixExports;
+    /**
+     * Get all TypeScript files in a directory recursively
+     */
+    private getAllTsFiles;
+}

package/dist/esm-fixer.js

@@ -0,0 +1,139 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EsmFixer = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Fixes relative imports in TypeScript files to include .js extensions for ESM compatibility
+ *
+ * Node.js ESM requires explicit file extensions for relative imports.
+ * This utility adds .js extensions to all relative import/export statements.
+ */
+class EsmFixer {
+    /**
+     * Fix all TypeScript files in a directory recursively
+     */
+    async fixDirectory(directory) {
+        console.log('Fixing ESM imports to add .js extensions...');
+        const files = this.getAllTsFiles(directory);
+        let fixedCount = 0;
+        for (const file of files) {
+            const fixed = await this.fixFile(file);
+            if (fixed) {
+                fixedCount++;
+            }
+        }
+        console.log(`✅ Fixed ${fixedCount} file(s) for ESM compatibility`);
+    }
+    /**
+     * Fix imports in a single file
+     * @returns true if file was modified, false otherwise
+     */
+    async fixFile(filePath) {
+        let content = fs.readFileSync(filePath, 'utf8');
+        const originalContent = content;
+        // Fix import statements
+        content = this.fixImports(content);
+        // Fix export statements
+        content = this.fixExports(content);
+        // Only write if content changed
+        if (content !== originalContent) {
+            fs.writeFileSync(filePath, content, 'utf8');
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Fix import statements to add .js extensions
+     */
+    fixImports(content) {
+        // Match: import ... from './relative/path'
+        // Don't match if already has extension (.js, .ts, .json)
+        // Don't match external packages (no . or ..)
+        const importRegex = /from\s+(['"])(\.|\.\.)(\/[^'"]*?)(?<!\.js|\.ts|\.json|\.mjs|\.cjs)\1/g;
+        return content.replace(importRegex, (match, quote, dots, importPath) => {
+            // Handle index imports: './models' -> './models/index.js'
+            // But only if the path doesn't already end with a filename
+            const hasFilename = /\/[^/]+$/.test(importPath);
+            if (!hasFilename && importPath.length > 0) {
+                // It's a directory import, add /index.js
+                return `from ${quote}${dots}${importPath}/index.js${quote}`;
+            }
+            // Normal file import, just add .js
+            return `from ${quote}${dots}${importPath}.js${quote}`;
+        });
+    }
+    /**
+     * Fix export statements to add .js extensions
+     */
+    fixExports(content) {
+        // Match: export ... from './relative/path'
+        // Don't match if already has extension
+        const exportRegex = /from\s+(['"])(\.|\.\.)(\/[^'"]*?)(?<!\.js|\.ts|\.json|\.mjs|\.cjs)\1/g;
+        return content.replace(exportRegex, (match, quote, dots, exportPath) => {
+            // Handle index exports
+            const hasFilename = /\/[^/]+$/.test(exportPath);
+            if (!hasFilename && exportPath.length > 0) {
+                return `from ${quote}${dots}${exportPath}/index.js${quote}`;
+            }
+            return `from ${quote}${dots}${exportPath}.js${quote}`;
+        });
+    }
+    /**
+     * Get all TypeScript files in a directory recursively
+     */
+    getAllTsFiles(directory) {
+        const files = [];
+        const walk = (dir) => {
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = path.join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    // Skip node_modules and hidden directories
+                    if (entry.name !== 'node_modules' && !entry.name.startsWith('.')) {
+                        walk(fullPath);
+                    }
+                }
+                else if (entry.isFile() && entry.name.endsWith('.ts')) {
+                    files.push(fullPath);
+                }
+            }
+        };
+        walk(directory);
+        return files;
+    }
+}
+exports.EsmFixer = EsmFixer;

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export { K8sClientGenerator, K8sClientGeneratorOptions, GenerationMode } from './k8s-client-generator';
 export { SpecDownloader, DownloadOptions } from './spec-downloader';
+export { EsmFixer } from './esm-fixer';

package/dist/index.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SpecDownloader = exports.K8sClientGenerator = void 0;
+exports.EsmFixer = exports.SpecDownloader = exports.K8sClientGenerator = void 0;
 var k8s_client_generator_1 = require("./k8s-client-generator");
 Object.defineProperty(exports, "K8sClientGenerator", { enumerable: true, get: function () { return k8s_client_generator_1.K8sClientGenerator; } });
 var spec_downloader_1 = require("./spec-downloader");
 Object.defineProperty(exports, "SpecDownloader", { enumerable: true, get: function () { return spec_downloader_1.SpecDownloader; } });
+var esm_fixer_1 = require("./esm-fixer");
+Object.defineProperty(exports, "EsmFixer", { enumerable: true, get: function () { return esm_fixer_1.EsmFixer; } });

package/dist/k8s-client-generator.d.ts

@@ -33,6 +33,11 @@ export interface K8sClientGeneratorOptions {
      * @default false
      */
     resolveReferences?: boolean;
+    /**
+     * Whether to fix imports by adding .js extensions for ESM compatibility
+     * @default false
+     */
+    fixEsmImports?: boolean;
     /**
      * Request timeout for downloading spec in milliseconds
      * @default 30000

package/dist/k8s-client-generator.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.K8sClientGenerator = void 0;
 const openapi_class_transformer_1 = require("openapi-class-transformer");
 const spec_downloader_1 = require("./spec-downloader");
+const esm_fixer_1 = require("./esm-fixer");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const yaml = __importStar(require("js-yaml"));
@@ -47,7 +48,7 @@ class K8sClientGenerator {
      * Generate TypeScript client from a remote OpenAPI spec URL
      */
     async generate(options) {
-        const { specUrl, outputDir, mode = 'full', headers, templateDir, keepSpec = false, resolveReferences = false, timeout, } = options;
+        const { specUrl, outputDir, mode = 'full', headers, templateDir, keepSpec = false, resolveReferences = false, fixEsmImports = false, timeout, } = options;
         let specPath;
         try {
             // Step 1: Download the OpenAPI spec
@@ -80,6 +81,12 @@ class K8sClientGenerator {
             }
             const generator = new openapi_class_transformer_1.Generator(generatorOptions);
             await generator.generate();
+            // Step 4: Fix ESM imports if requested
+            if (fixEsmImports) {
+                console.log('Step 4: Fixing ESM imports...');
+                const esmFixer = new esm_fixer_1.EsmFixer();
+                await esmFixer.fixDirectory(outputDir);
+            }
             console.log('✅ Client generation completed successfully!');
             console.log(`📁 Generated files location: ${outputDir}`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klasik",
-  "version": "1.0.17",
+  "version": "1.0.20",
   "description": "Download OpenAPI specs from remote URLs and generate TypeScript clients with class-transformer support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",