zod-codegen 1.0.3 → 1.1.1

package/PERFORMANCE.md

@@ -0,0 +1,59 @@
+# Build Performance
+
+## Current Build Time
+
+- **Standard TypeScript (`tsc`)**: ~1.2 seconds
+- **Project size**: 19 TypeScript files, ~184KB
+
+## TypeScript Native Preview (TSGO)
+
+For even faster builds, you can optionally use the TypeScript Native Preview (TSGO), a Go-based compiler that can be up to 10x faster.
+
+### Installation
+
+```bash
+npm install -D @typescript/native-preview
+```
+
+### Usage
+
+```bash
+# Use native compiler for builds
+npm run build:native
+
+# Or use directly
+npx tsgo --project tsconfig.json
+```
+
+### Notes
+
+- **Status**: Still in preview/experimental phase
+- **Compatibility**: May not support all TypeScript features yet
+- **Best for**: Large codebases where build time is a bottleneck
+- **Current project**: Build is already fast (~1.2s), so the benefit is minimal
+
+### When to Use TSGO
+
+✅ **Use TSGO if:**
+
+- You have a large codebase (>100 files)
+- Build time is >5 seconds
+- You're willing to test experimental features
+
+❌ **Stick with `tsc` if:**
+
+- Your build is already fast (<2 seconds)
+- You need 100% feature compatibility
+- You're in production
+
+### Benchmarking
+
+To compare performance:
+
+```bash
+# Standard TypeScript
+time npm run build
+
+# Native TypeScript
+time npm run build:native
+```

package/README.md

@@ -10,13 +10,18 @@ A powerful TypeScript code generator that creates **Zod schemas** and **type-saf
 
 ## 🚀 Features
 
-- **🔥 Zod Schema Generation**: Automatically generate Zod validation schemas from OpenAPI specs
-- **🎯 Type-Safe**: Full TypeScript support with generated types
-- **📡 Multiple Formats**: Support for OpenAPI 3.x, Swagger 2.0, JSON, and YAML
-- **🌐 Remote Files**: Fetch OpenAPI specs from URLs
+- **🔥 Zod Schema Generation**: Automatically generate Zod validation schemas from OpenAPI component schemas
+- **🎯 Type-Safe Client**: Generate a fully type-safe API client class with methods for each endpoint
+- **📡 Multiple Formats**: Support for OpenAPI 3.x specifications in JSON and YAML formats
+- **🌐 Remote Files**: Fetch OpenAPI specs from URLs using native fetch API
 - **⚡ Fast**: Optimized for performance with minimal dependencies
-- **🔧 Configurable**: Flexible output options and customization
-- **📦 CLI & Programmatic**: Use as a CLI tool or integrate into your build process
+- **🔧 Advanced Schema Support**: Handles logical operators (anyOf, oneOf, allOf, not), enums, discriminators, and complex nested schemas
+- **📦 Single File Output**: Generates all schemas and client in one convenient TypeScript file
+- **🛡️ Runtime Validation**: Built-in Zod validation for request/response data
+- **🌍 Form Support**: Supports both JSON and form-urlencoded request bodies
+- **🔐 Extensible**: Override `getBaseRequestOptions()` to add authentication, custom headers, CORS, and other fetch options
+- **🌐 Server Configuration**: Full support for OpenAPI server variables and templating (e.g., `{environment}.example.com`)
+- **⚙️ Flexible Client Options**: Options-based constructor supporting server selection, variable overrides, and custom base URLs
 
 ## 📦 Installation
 
@@ -61,35 +66,85 @@ zod-codegen -i ./swagger.yaml -o ./src/generated
 ```typescript
 import {Generator} from 'zod-codegen';
 
-const generator = new Generator();
-
-// Generate from local file
-await generator.generate({
-  input: './openapi.json',
-  output: './generated',
-});
-
-// Generate from URL
-await generator.generate({
-  input: 'https://api.example.com/openapi.json',
-  output: './api',
-});
+// Create a simple reporter object
+const reporter = {
+  log: (...args: unknown[]) => console.log(...args),
+  error: (...args: unknown[]) => console.error(...args),
+};
+
+// Create generator instance
+const generator = new Generator(
+  'my-app',
+  '1.0.0',
+  reporter,
+  './openapi.json', // Input path or URL
+  './generated', // Output directory
+);
+
+// Run the generator
+const exitCode = await generator.run();
 ```
 
 ## 📁 Generated Output
 
-The generator creates the following structure:
+The generator creates a single TypeScript file (`type.ts`) containing:
+
+- **Zod Schemas**: Exported Zod validation schemas for all component schemas defined in your OpenAPI spec
+- **API Client Class**: A type-safe client class with methods for each endpoint operation
+- **Server Configuration**: `serverConfigurations` array and `defaultBaseUrl` constant extracted from OpenAPI servers
+- **Client Options Type**: `ClientOptions` type for flexible server selection and variable overrides
+- **Protected Extension Point**: A `getBaseRequestOptions()` method that can be overridden for customization
+
+### Generated Client Structure
+
+The generated client class includes:
+
+```typescript
+export class YourAPI {
+  readonly #baseUrl: string;
+
+  // Options-based constructor (if servers are defined in OpenAPI spec)
+  constructor(options: ClientOptions);
+
+  // Or simple baseUrl constructor (if no servers defined)
+  constructor(baseUrl: string = '/', _?: unknown);
+
+  // Protected method - override to customize request options
+  protected getBaseRequestOptions(): Partial<Omit<RequestInit, 'method' | 'body'>>;
+
+  // Private method - handles all HTTP requests
+  async #makeRequest<T>(method: string, path: string, options: {...}): Promise<T>;
+
+  // Generated endpoint methods (one per operationId)
+  async yourEndpointMethod(...): Promise<ResponseType>;
+}
+
+// ClientOptions type (when servers are defined)
+export type ClientOptions = {
+  baseUrl?: string;                    // Override base URL directly
+  serverIndex?: number;                // Select server by index (0-based)
+  serverVariables?: Record<string, string>; // Override server template variables
+};
+
+// Server configuration (when servers are defined)
+export const serverConfigurations: Array<{
+  url: string;
+  description?: string;
+  variables?: Record<string, {
+    default: string;
+    enum?: string[];
+    description?: string;
+  }>;
+}>;
+
+export const defaultBaseUrl: string;   // First server with default variables
+```
+
+### File Structure
 
 ```
 generated/
-├── schemas/           # Zod validation schemas
-│   ├── user.schema.ts
-│   └── product.schema.ts
-├── types/            # TypeScript type definitions
-│   ├── user.types.ts
-│   └── product.types.ts
-└── client/           # Type-safe API client
-    └── api.client.ts
+└── type.ts           # All schemas and client in one file
 ```
 
 ## 🎯 Example
@@ -101,69 +156,228 @@ openapi: 3.0.0
 info:
   title: User API
   version: 1.0.0
+servers:
+  - url: https://api.example.com
 paths:
-  /users:
+  /users/{id}:
     get:
+      operationId: getUserById
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: integer
       responses:
         '200':
           content:
             application/json:
               schema:
-                type: object
-                properties:
-                  id:
-                    type: integer
-                  name:
-                    type: string
-                  email:
-                    type: string
-                    format: email
-                required: [id, name, email]
+                $ref: '#/components/schemas/User'
+components:
+  schemas:
+    User:
+      type: object
+      properties:
+        id:
+          type: integer
+        name:
+          type: string
+        email:
+          type: string
+          format: email
+      required: [id, name, email]
 ```
 
-**Generated Zod Schema** (`schemas/user.schema.ts`):
+**Generated Output** (`generated/type.ts`):
 
 ```typescript
 import {z} from 'zod';
 
-export const UserSchema = z.object({
+// Components schemas
+export const User = z.object({
   id: z.number().int(),
   name: z.string(),
   email: z.string().email(),
 });
 
-export type User = z.infer<typeof UserSchema>;
+// Server configuration (when servers are defined in OpenAPI spec)
+export const serverConfigurations = [
+  {
+    url: 'https://api.example.com',
+  },
+];
+export const defaultBaseUrl = 'https://api.example.com';
+export type ClientOptions = {
+  baseUrl?: string;
+  serverIndex?: number;
+  serverVariables?: Record<string, string>;
+};
+
+// Client class
+export class UserAPI {
+  readonly #baseUrl: string;
+
+  constructor(options: ClientOptions = {}) {
+    this.#baseUrl = options.baseUrl || defaultBaseUrl;
+  }
+
+  protected getBaseRequestOptions(): Partial<Omit<RequestInit, 'method' | 'body'>> {
+    return {};
+  }
+
+  async getUserById(id: number): Promise<z.infer<typeof User>> {
+    return User.parse(await this.#makeRequest<z.infer<typeof User>>('GET', `/users/${id}`, {}));
+  }
+
+  // ... private #makeRequest method
+}
+```
+
+**Usage:**
+
+```typescript
+import {UserAPI, User} from './generated/type.js';
+
+// Use default server from OpenAPI spec
+const client = new UserAPI({});
+const user = await client.getUserById(123);
+// user is fully typed and validated!
 ```
 
-**Generated Types** (`types/user.types.ts`):
+### Extending the Client
+
+The generated client includes a protected `getBaseRequestOptions()` method that you can override to customize request options. This method returns `Partial<Omit<RequestInit, 'method' | 'body'>>`, allowing you to configure:
+
+- **Headers**: Authentication tokens, User-Agent, custom headers
+- **CORS**: `mode`, `credentials` for cross-origin requests
+- **Request Options**: `signal` (AbortController), `cache`, `redirect`, `referrer`, etc.
+
+**Important**: Options from `getBaseRequestOptions()` are **merged with** (not replaced by) request-specific options. Base options like `mode`, `credentials`, and `signal` are preserved, while headers are merged (base headers + Content-Type + request headers). See [EXAMPLES.md](EXAMPLES.md) for detailed merging behavior.
+
+#### Basic Authentication Example
 
 ```typescript
-export interface User {
-  id: number;
-  name: string;
-  email: string;
+import {UserAPI, ClientOptions} from './generated/type.js';
+
+class AuthenticatedUserAPI extends UserAPI {
+  private accessToken: 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.accessToken ? {Authorization: `Bearer ${this.accessToken}`} : {}),
+      },
+    };
+  }
+
+  setAccessToken(token: string): void {
+    this.accessToken = token;
+  }
 }
+
+// Usage
+const client = new AuthenticatedUserAPI({});
+client.setAccessToken('your-token-here');
+const user = await client.getUserById(123); // Includes Authorization header
 ```
 
-**Generated Client** (`client/api.client.ts`):
+#### Complete Configuration Example
 
 ```typescript
-import {UserSchema, type User} from '../schemas/user.schema.js';
+import {UserAPI, ClientOptions} from './generated/type.js';
+
+class FullyConfiguredAPI extends UserAPI {
+  private accessToken: string | null = null;
+
+  constructor(options: ClientOptions = {}) {
+    super(options);
+  }
 
-export class ApiClient {
-  async getUsers(): Promise<User[]> {
-    const response = await fetch('/api/users');
-    const data = await response.json();
-    return UserSchema.array().parse(data);
+  protected getBaseRequestOptions(): Partial<Omit<RequestInit, 'method' | 'body'>> {
+    const options = super.getBaseRequestOptions();
+    return {
+      ...options,
+      headers: {
+        ...((options.headers as Record<string, string>) || {}),
+        'User-Agent': 'MyApp/1.0.0',
+        ...(this.accessToken ? {Authorization: `Bearer ${this.accessToken}`} : {}),
+      },
+      mode: 'cors',
+      credentials: 'include',
+      cache: 'no-cache',
+    };
+  }
+
+  setAccessToken(token: string): void {
+    this.accessToken = token;
   }
 }
+
+// Usage
+const client = new FullyConfiguredAPI({});
+client.setAccessToken('your-token');
 ```
 
+#### Available Request Options
+
+You can set any `RequestInit` option except `method` and `body` (which are controlled by the generated code):
+
+| Option           | Type                 | Description                                                         |
+| ---------------- | -------------------- | ------------------------------------------------------------------- |
+| `headers`        | `HeadersInit`        | Request headers (authentication, User-Agent, etc.)                  |
+| `signal`         | `AbortSignal`        | AbortController signal for request cancellation                     |
+| `credentials`    | `RequestCredentials` | CORS credentials mode (`'include'`, `'same-origin'`, `'omit'`)      |
+| `mode`           | `RequestMode`        | Request mode (`'cors'`, `'no-cors'`, `'same-origin'`, `'navigate'`) |
+| `cache`          | `RequestCache`       | Cache mode (`'default'`, `'no-cache'`, `'reload'`, etc.)            |
+| `redirect`       | `RequestRedirect`    | Redirect handling (`'follow'`, `'error'`, `'manual'`)               |
+| `referrer`       | `string`             | Referrer URL                                                        |
+| `referrerPolicy` | `ReferrerPolicy`     | Referrer policy                                                     |
+| `integrity`      | `string`             | Subresource integrity hash                                          |
+| `keepalive`      | `boolean`            | Keep connection alive                                               |
+
+See [EXAMPLES.md](EXAMPLES.md) for comprehensive examples including:
+
+- Bearer token authentication
+- Session management with token refresh
+- Custom User-Agent headers
+- CORS configuration
+- Request cancellation with AbortController
+- Environment-specific configurations
+
+## 📖 Examples
+
+Check out the [examples directory](./examples/) for complete, runnable examples:
+
+- **[Petstore API](./examples/petstore/)** - Complete example with the Swagger Petstore API
+- **[PokéAPI](./examples/pokeapi/)** - Example with a public REST API
+
+Each example includes:
+
+- Generated client code
+- Basic usage examples
+- Authentication examples
+- README with instructions
+
+## 📚 Documentation
+
+- **[README.md](README.md)** - Project overview and quick start guide
+- **[EXAMPLES.md](EXAMPLES.md)** - Comprehensive examples and patterns for extending the client
+- **[CONTRIBUTING.md](CONTRIBUTING.md)** - Guidelines for contributing to the project
+- **[CHANGELOG.md](CHANGELOG.md)** - Version history and changes
+
 ## 🛠️ Development
 
 ### Prerequisites
 
-- Node.js ≥ 18.0.0
+- Node.js ≥ 24.11.1
 - npm or yarn
 
 ### Setup
@@ -223,9 +437,9 @@ npm run test:ui
 
 ## 📋 Requirements
 
-- **Node.js**: ≥ 18.0.0
-- **TypeScript**: ≥ 5.0.0
-- **Zod**: ≥ 3.20.0
+- **Node.js**: ≥ 24.11.1
+- **TypeScript**: ≥ 5.9.3
+- **Zod**: ≥ 4.1.12
 
 ## 🤝 Contributing