zod-codegen 1.0.3 → 1.1.0

package/dist/tests/unit/generator.test.js

@@ -1,30 +1,100 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { Generator } from '../../src/generator.js';
 import { Reporter } from '../../src/utils/reporter.js';
+import { readFileSync, existsSync, mkdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const testOutputDir = join(__dirname, '../../test-output');
 describe('Generator', () => {
     let generator;
     let mockReporter;
     beforeEach(() => {
+        // Clean up test output directory
+        if (existsSync(testOutputDir)) {
+            rmSync(testOutputDir, { recursive: true, force: true });
+        }
+        mkdirSync(testOutputDir, { recursive: true });
         // Create a mock reporter
         mockReporter = {
-            info: vi.fn(),
+            log: vi.fn(),
             error: vi.fn(),
-            warn: vi.fn(),
-            success: vi.fn(),
         };
-        generator = new Generator('test-app', '1.0.0', mockReporter, './test-input.json', './test-output');
+    });
+    afterEach(() => {
+        // Clean up test output directory
+        if (existsSync(testOutputDir)) {
+            rmSync(testOutputDir, { recursive: true, force: true });
+        }
     });
     describe('constructor', () => {
         it('should create a new Generator instance', () => {
+            generator = new Generator('test-app', '1.0.0', mockReporter, './samples/swagger-petstore.yaml', testOutputDir);
             expect(generator).toBeInstanceOf(Generator);
         });
+        it('should initialize with correct parameters', () => {
+            generator = new Generator('test-app', '1.0.0', mockReporter, './samples/swagger-petstore.yaml', testOutputDir);
+            expect(generator).toBeDefined();
+        });
     });
     describe('run', () => {
         it('should be a function', () => {
+            generator = new Generator('test-app', '1.0.0', mockReporter, './samples/swagger-petstore.yaml', testOutputDir);
             expect(typeof generator.run).toBe('function');
         });
-        it('should have the run method defined', () => {
-            expect(generator).toHaveProperty('run');
+        it('should generate code from a valid OpenAPI file', async () => {
+            generator = new Generator('test-app', '1.0.0', mockReporter, './samples/swagger-petstore.yaml', testOutputDir);
+            const exitCode = await generator.run();
+            expect(exitCode).toBe(0);
+            expect(mockReporter.log).toHaveBeenCalled();
+            expect(mockReporter.error).not.toHaveBeenCalled();
+            // Verify output file was created
+            const outputFile = join(testOutputDir, 'type.ts');
+            expect(existsSync(outputFile)).toBe(true);
+            // Verify file contains expected content
+            const content = readFileSync(outputFile, 'utf-8');
+            expect(content).toMatch(/import\s*{\s*z\s*}\s*from\s*['"]zod['"]/);
+            expect(content).toContain('export class');
+            expect(content).toContain('getBaseRequestOptions');
+        });
+        it('should handle invalid file paths gracefully', async () => {
+            generator = new Generator('test-app', '1.0.0', mockReporter, './non-existent-file.yaml', testOutputDir);
+            const exitCode = await generator.run();
+            expect(exitCode).toBe(1);
+            expect(mockReporter.error).toHaveBeenCalled();
+        });
+        it('should handle invalid OpenAPI specifications', async () => {
+            // Create a temporary invalid OpenAPI file
+            const invalidFile = join(testOutputDir, 'invalid.yaml');
+            mkdirSync(testOutputDir, { recursive: true });
+            readFileSync; // Ensure we can write
+            const { writeFileSync } = await import('node:fs');
+            writeFileSync(invalidFile, 'invalid: yaml: content: [unclosed');
+            generator = new Generator('test-app', '1.0.0', mockReporter, invalidFile, testOutputDir);
+            const exitCode = await generator.run();
+            expect(exitCode).toBe(1);
+            expect(mockReporter.error).toHaveBeenCalled();
+        });
+        it('should generate code with correct structure', async () => {
+            generator = new Generator('test-app', '1.0.0', mockReporter, './samples/swagger-petstore.yaml', testOutputDir);
+            await generator.run();
+            const outputFile = join(testOutputDir, 'type.ts');
+            const content = readFileSync(outputFile, 'utf-8');
+            // Check for key components
+            expect(content).toMatch(/import\s*{\s*z\s*}\s*from\s*['"]zod['"]/);
+            expect(content).toContain('export const');
+            expect(content).toContain('protected getBaseRequestOptions');
+            expect(content).toContain('async #makeRequest');
+        });
+        it('should include header comments in generated file', async () => {
+            generator = new Generator('test-app', '1.0.0', mockReporter, './samples/swagger-petstore.yaml', testOutputDir);
+            await generator.run();
+            const outputFile = join(testOutputDir, 'type.ts');
+            const content = readFileSync(outputFile, 'utf-8');
+            expect(content).toContain('AUTOGENERATED');
+            expect(content).toContain('test-app@1.0.0');
+            expect(content).toContain('eslint-disable');
         });
     });
 });

package/eslint.config.mjs

@@ -10,6 +10,7 @@ export default defineConfig([
       'node_modules/**/*',
       '**/*.test*.ts',
       '**/coverage/*',
+      'examples/**/*.ts',
     ],
   },
   eslint.configs.recommended,

package/examples/.gitkeep

@@ -0,0 +1,3 @@
+# This file ensures the examples directory is tracked by git
+# Generated type.ts files are ignored via .gitignore
+

package/examples/README.md

@@ -0,0 +1,74 @@
+# Examples
+
+This directory contains example implementations demonstrating how to use `zod-codegen` with real-world OpenAPI specifications.
+
+## Available Examples
+
+### 🐾 [Petstore API](./petstore/)
+
+The Swagger Petstore API is a well-known example API that demonstrates various OpenAPI features. This example shows:
+
+- Basic client usage
+- Authentication with API keys
+- Extending the client for custom headers
+- Working with pets, orders, and users
+
+**Generate the client:**
+
+```bash
+zod-codegen --input ./samples/swagger-petstore.yaml --output ./examples/petstore
+```
+
+**Run examples:**
+
+```bash
+npx ts-node examples/petstore/basic-usage.ts
+npx ts-node examples/petstore/authenticated-usage.ts
+```
+
+### ⚡ [PokéAPI](./pokeapi/)
+
+PokéAPI is a public RESTful API that provides data about Pokémon. This example demonstrates:
+
+- Working with a real-world public API
+- Fetching Pokémon data
+- Custom client configuration
+
+**Generate the client:**
+
+```bash
+zod-codegen --input https://pokeapi.co/api/v2/openapi.json --output ./examples/pokeapi
+```
+
+## Structure
+
+Each example directory contains:
+
+- `type.ts` - Generated client and schemas (created by zod-codegen)
+- `README.md` - Example-specific documentation
+- `basic-usage.ts` - Basic usage examples
+- `authenticated-usage.ts` - Authentication examples (if applicable)
+
+## Getting Started
+
+1. **Choose an example** that matches your use case
+2. **Generate the client** using the command shown in the example's README
+3. **Review the generated code** in `type.ts`
+4. **Run the example scripts** to see it in action
+5. **Extend the client** using patterns from [EXAMPLES.md](../EXAMPLES.md)
+
+## Learning Path
+
+1. Start with **Petstore** to understand basic concepts
+2. Try **PokéAPI** to see a real-world public API
+3. Read [EXAMPLES.md](../EXAMPLES.md) for advanced patterns
+4. Create your own example with your API!
+
+## Contributing Examples
+
+If you'd like to add an example:
+
+1. Create a new directory under `examples/`
+2. Add a `README.md` explaining the example
+3. Include example TypeScript files
+4. Update this README to list your example

package/examples/petstore/README.md

@@ -0,0 +1,121 @@
+# Petstore API Example
+
+This example demonstrates how to use `zod-codegen` with the Swagger Petstore OpenAPI specification.
+
+## Generated Files
+
+After running `zod-codegen`, you'll get:
+
+- `type.ts` - Contains all Zod schemas and the generated API client
+
+## Basic Usage
+
+```typescript
+import {SwaggerPetstoreOpenAPI30} from './type.js';
+
+// Create a client instance using default server from OpenAPI spec
+const client = new SwaggerPetstoreOpenAPI30({});
+
+// Use the generated methods
+const pets = await client.findPetsByStatus('available');
+console.log('Available pets:', pets);
+```
+
+### Server Configuration Options
+
+The generated client supports flexible server configuration:
+
+```typescript
+import {SwaggerPetstoreOpenAPI30, ClientOptions} from './type.js';
+
+// Option 1: Use default server (first server from OpenAPI spec)
+const defaultClient = new SwaggerPetstoreOpenAPI30({});
+
+// Option 2: Override with custom base URL
+const customClient = new SwaggerPetstoreOpenAPI30({
+  baseUrl: 'https://custom-api.example.com/v3',
+});
+
+// Option 3: Select server by index (if multiple servers exist)
+const indexedClient = new SwaggerPetstoreOpenAPI30({
+  serverIndex: 0,
+});
+
+// Option 4: Use server variables (if your OpenAPI spec has templated URLs)
+// Example spec: https://{environment}.example.com:{port}/v{version}
+const variableClient = new SwaggerPetstoreOpenAPI30({
+  serverIndex: 0,
+  serverVariables: {
+    environment: 'api.staging',
+    port: '8443',
+    version: '2',
+  },
+});
+```
+
+## Example: Finding Pets
+
+```typescript
+import {SwaggerPetstoreOpenAPI30, defaultBaseUrl} from './type.js';
+
+async function findAvailablePets() {
+  const client = new SwaggerPetstoreOpenAPI30(defaultBaseUrl);
+
+  try {
+    // Find pets by status
+    const availablePets = await client.findPetsByStatus('available');
+    console.log(`Found ${availablePets.length} available pets`);
+
+    // Find pets by tags
+    const taggedPets = await client.findPetsByTags(['friendly', 'cute']);
+    console.log(`Found ${taggedPets.length} tagged pets`);
+
+    // Get a specific pet by ID
+    const pet = await client.getPetById(1);
+    console.log('Pet details:', pet);
+  } catch (error) {
+    console.error('Error fetching pets:', error);
+  }
+}
+
+findAvailablePets();
+```
+
+## Example: Adding a Pet
+
+```typescript
+import {SwaggerPetstoreOpenAPI30, Pet, PetStatus, defaultBaseUrl} from './type.js';
+import {z} from 'zod';
+
+async function addNewPet() {
+  const client = new SwaggerPetstoreOpenAPI30(defaultBaseUrl);
+
+  const newPet: z.infer<typeof Pet> = {
+    id: 12345,
+    name: 'Fluffy',
+    status: PetStatus.enum.available,
+    category: {
+      id: 1,
+      name: 'Dogs',
+    },
+    photoUrls: ['https://example.com/fluffy.jpg'],
+    tags: [
+      {id: 1, name: 'friendly'},
+      {id: 2, name: 'cute'},
+    ],
+  };
+
+  try {
+    const addedPet = await client.addPet(newPet);
+    console.log('Pet added:', addedPet);
+  } catch (error) {
+    console.error('Error adding pet:', error);
+  }
+}
+
+addNewPet();
+```
+
+## Example: Extending the Client
+
+See the main [EXAMPLES.md](../../EXAMPLES.md) for comprehensive examples on extending the client for authentication, CORS, and custom headers.

package/examples/petstore/authenticated-usage.ts

@@ -0,0 +1,60 @@
+/**
+ * Example showing how to extend the generated client for authentication
+ *
+ * Run with: npx ts-node examples/petstore/authenticated-usage.ts
+ */
+
+import {SwaggerPetstoreOpenAPI30, ClientOptions} from './type.js';
+
+class AuthenticatedPetstoreAPI extends SwaggerPetstoreOpenAPI30 {
+  private apiKey: string | null = null;
+
+  constructor(options: ClientOptions = {}) {
+    super(options);
+  }
+
+  protected getBaseRequestOptions(): Partial<Omit<RequestInit, 'method' | 'body'>> {
+    const options = super.getBaseRequestOptions();
+    return {
+      ...options,
+      headers: {
+        ...((options.headers as Record<string, string>) || {}),
+        ...(this.apiKey ? {api_key: this.apiKey} : {}),
+        'User-Agent': 'PetstoreClient/1.0.0',
+      },
+    };
+  }
+
+  setApiKey(key: string): void {
+    this.apiKey = key;
+  }
+
+  clearApiKey(): void {
+    this.apiKey = null;
+  }
+}
+
+async function main() {
+  const client = new AuthenticatedPetstoreAPI({});
+
+  // Set API key for authenticated requests
+  client.setApiKey('your-api-key-here');
+
+  try {
+    console.log('🔐 Making authenticated request...\n');
+
+    // This endpoint typically requires authentication
+    const inventory = await client.getInventory();
+    console.log('✅ Inventory retrieved:');
+    console.log(JSON.stringify(inventory, null, 2));
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error('❌ Error:', error.message);
+    } else {
+      console.error('❌ Unknown error:', error);
+    }
+    process.exit(1);
+  }
+}
+
+void main();

package/examples/petstore/basic-usage.ts

@@ -0,0 +1,51 @@
+/**
+ * Basic usage example for the generated Petstore API client
+ *
+ * Run with: npx ts-node examples/petstore/basic-usage.ts
+ */
+
+import {SwaggerPetstoreOpenAPI30} from './type.js';
+
+async function main() {
+  // Use default server (first server from OpenAPI spec)
+  const client = new SwaggerPetstoreOpenAPI30({});
+
+  try {
+    console.log('🔍 Finding available pets...\n');
+
+    // Find pets by status
+    const availablePets = await client.findPetsByStatus('available');
+    console.log(`✅ Found ${availablePets.length} available pets`);
+
+    if (availablePets.length > 0) {
+      console.log('\n📋 First pet details:');
+      console.log(JSON.stringify(availablePets[0], null, 2));
+    }
+
+    // Find pets by tags (if available)
+    try {
+      const taggedPets = await client.findPetsByTags(['friendly']);
+      console.log(`\n🏷️  Found ${taggedPets.length} pets with tags`);
+    } catch (error) {
+      console.log('\n⚠️  Tags endpoint may not be available');
+    }
+
+    // Get store inventory
+    try {
+      const inventory = await client.getInventory();
+      console.log('\n📦 Store inventory:');
+      console.log(JSON.stringify(inventory, null, 2));
+    } catch (error) {
+      console.log('\n⚠️  Inventory endpoint may require authentication');
+    }
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error('❌ Error:', error.message);
+    } else {
+      console.error('❌ Unknown error:', error);
+    }
+    process.exit(1);
+  }
+}
+
+void main();

package/examples/petstore/server-variables-usage.ts

@@ -0,0 +1,63 @@
+/**
+ * Example showing how to use server variables for different environments
+ *
+ * Run with: npx ts-node examples/petstore/server-variables-usage.ts
+ *
+ * Note: This example uses a hypothetical API with server variables.
+ * For a real example, generate a client from an OpenAPI spec with server variables.
+ */
+
+import {SwaggerPetstoreOpenAPI30, ClientOptions} from './type.js';
+
+async function main() {
+  // Example 1: Use default server (first server from OpenAPI spec)
+  console.log('📡 Example 1: Using default server\n');
+  const defaultClient = new SwaggerPetstoreOpenAPI30({});
+  console.log('Default client created');
+
+  // Example 2: Override with custom baseUrl
+  console.log('\n📡 Example 2: Overriding with custom baseUrl\n');
+  const customClient = new SwaggerPetstoreOpenAPI30({
+    baseUrl: 'https://custom-api.example.com/v3',
+  });
+  console.log('Custom client created');
+
+  // Example 3: Select different server by index (if multiple servers exist)
+  console.log('\n📡 Example 3: Selecting server by index\n');
+  const indexedClient = new SwaggerPetstoreOpenAPI30({
+    serverIndex: 0, // Use first server
+  });
+  console.log('Indexed client created');
+
+  // Example 4: Using server variables (if your OpenAPI spec has templated URLs)
+  // For example: https://{environment}.example.com:{port}/v{version}
+  console.log('\n📡 Example 4: Using server variables\n');
+  const variableClient = new SwaggerPetstoreOpenAPI30({
+    serverIndex: 0,
+    serverVariables: {
+      // environment: 'api.staging',  // Uncomment if your spec has these variables
+      // port: '8443',
+      // version: '2',
+    },
+  });
+  console.log('Variable client created');
+
+  // Example 5: Combining server selection with custom baseUrl override
+  console.log('\n📡 Example 5: Combining options\n');
+  const combinedClient = new SwaggerPetstoreOpenAPI30({
+    serverIndex: 0,
+    serverVariables: {
+      // Add variables here if your spec supports them
+    },
+    // baseUrl takes precedence if provided
+    // baseUrl: 'https://override.example.com',
+  });
+  console.log('Combined client created');
+
+  console.log('\n✅ All examples completed!');
+  console.log("\n💡 Tip: Check your OpenAPI spec's servers array to see available options.");
+  console.log('   Server variables allow you to switch between environments (dev, staging, prod)');
+  console.log('   without changing code!');
+}
+
+void main();