prisma-zod-generator 1.2.0 → 1.3.0

package/README.md

@@ -23,196 +23,180 @@
   </p>
 
   <p>
-    <strong>🎯 Zero-config • 🛡️ Type-safe • ⚡ Fast • 🔧 Customizable</strong>
+    <strong>:dart: Zero-config • :shield: Type-safe • :zap: Fast • :wrench: Customizable</strong>
   </p>
 
 </div>
 
 ---
 
-<br>
-
 <div align="center">
-  <h3>💡 Transform your Prisma schema into type-safe validation schemas</h3>
+  <h3>:bulb: Transform your Prisma schema into type-safe validation schemas</h3>
   <p><em>Automatically generates Zod schemas for all Prisma operations with full TypeScript support</em></p>
 </div>
 
 <div align="center">
   
-  ## 💖 **Support This Project**
+  <a id="sponsor"></a>
+  ## :sparkling_heart: Sponsor to Keep This Project Active
   
-  <p><em>If this tool accelerates your development, consider supporting its growth</em></p>
+  <p><strong>:rotating_light: Active maintenance depends on your sponsorship. If this generator saves you time, please consider sponsoring.</strong></p>
   
   <a href="https://github.com/sponsors/omar-dulaimi">
     <img src="https://img.shields.io/badge/💝_Sponsor_on_GitHub-ea4aaa?style=for-the-badge&logo=github&logoColor=white" alt="GitHub Sponsors" height="45">
   </a>
   
-  <p><strong>✨ Your sponsorship drives innovation and keeps this project thriving ✨</strong></p>
+  <p><em>Your support funds maintenance, issue triage, new features, documentation, and community help.</em></p>
   
 </div>
 
+---
 
-### ✨ **Core Features**
 
-<div align="center">
-  
-  | 🚀 **Feature** | 📦 **Version** | 🎯 **Benefit** |
-  |----------------|----------------|------------------|
-  | **New Prisma Client** | `6.12.0+` | 🆕 ESM-compatible generator support |
-  | **Prisma** | `6.12.0+` | 🏃‍♂️ Latest features & performance |
-  | **Zod** | `4.0.5+` | 🛡️ Enhanced validation & type safety |
-  | **TypeScript** | `5.8+` | ⚡ Cutting-edge language features |
-  | **Testing** | `Vitest 3` | 🧪 Comprehensive coverage |
-  | **Tooling** | `ESLint 9` | 🔧 Modern dev experience |
-  | **Multi-DB** | `All Providers` | 🗄️ PostgreSQL, MySQL, MongoDB, SQLite+ |
-  
-</div>
 
-<div align="center">
-  
-  ### 📦 **Installation**
-  
-</div>
+## :clipboard: **Table of Contents**
+
+<table>
+  <tr>
+  <td><a href="#sponsor">:sparkling_heart: Sponsor</a></td>
+  <td><a href="#-quick-start">:rocket: Quick Start</a></td>
+  <td><a href="#-generated-output">:clipboard: Generated Output</a></td>
+  <td><a href="#-version-compatibility">:package: Compatibility</a></td>
+  <td><a href="#-core-examples">:books: Core Examples</a></td>
+  </tr>
+  <tr>
+  <td><a href="#-advanced-features">:wrench: Advanced Features</a></td>
+  <td><a href="#-configuration">:gear: Configuration</a></td>
+  <td><a href="#-api-reference">:book: API Reference</a></td>
+  <td><a href="#-framework-examples">:globe_with_meridians: Framework Examples</a></td>
+  </tr>
+  <td><a href="#-testing--development">:test_tube: Testing & Development</a></td>
+  <td><a href="#-troubleshooting">:mag: Troubleshooting</a></td>
+  <td><a href="#-contributing">:handshake: Contributing</a></td>
+    <td></td>
+  </tr>
+</table>
+
+---
+
+## :rocket: Quick Start
+
+### Installation
 
 ```bash
-# 🚀 Install the latest release
+# NPM
 npm install prisma-zod-generator
+
+# Yarn
+yarn add prisma-zod-generator
+
+# PNPM  
+pnpm add prisma-zod-generator
 ```
 
-### 🔄 Upgrading
+### 2. Add generator block to your Prisma schema
 
-The latest stable version maintains full API compatibility. Requirements:
-- **Node.js 18+** 
-- **Prisma 6.12.0+** 
-- **Zod 4.0.5+** 
+Add the Prisma Zod Generator to your `schema.prisma` with inline options. You can also supply a JSON config via `config` for advanced/nested settings.
 
-Simply update your dependencies and re-run `npx prisma generate` - no code changes needed!
+```prisma
+generator zod {
+  provider = "prisma-zod-generator"        // required: package id
+  output   = "./generated"                  // required: where to write output
+
+  // File output mode
+  useMultipleFiles       = true              // true: multi-file (default), false: single-file bundle
+  singleFileName         = "schemas.ts"     // only when useMultipleFiles=false
+  placeSingleFileAtRoot  = true              // single-file at output root (true) or under schemas/ (false)
+
+  // Legacy select/include flags (override JSON config if both provided)
+  isGenerateSelect       = false
+  isGenerateInclude      = false
+
+  // Optional: external JSON config for nested options (models, variants, exclusions, etc.)
+  // When both sources specify the same simple option, this generator block wins.
+  config                 = "./zod-generator.config.json"
+}
+```
+
+### 3. Configure TypeScript (required)
+
+```json
+{
+  "compilerOptions": {
+    "strict": true
+  }
+}
+```
+
+### 4. Generate schemas
 
 ```bash
-npm update prisma-zod-generator
 npx prisma generate
 ```
 
-<div align="center">
-  
-  ## 📚 **Navigation**
-  
-  <table>
-    <tr>
-      <td><a href="#-features">✨ Features</a></td>
-      <td><a href="#-quick-start">🚀 Quick Start</a></td>
-      <td><a href="#-generated-output">📋 Output</a></td>
-      <td><a href="#️-configuration-options">⚙️ Config</a></td>
-    </tr>
-    <tr>
-      <td><a href="#-advanced-usage">🔧 Advanced</a></td>
-      <td><a href="#-examples">📚 Examples</a></td>
-      <td><a href="#-troubleshooting">🔍 Troubleshooting</a></td>
-      <td><a href="#-contributing">🤝 Contributing</a></td>
-    </tr>
-  </table>
-  
-</div>
+---
 
-<div align="center">
-  
-  ## ✨ **Why Choose Prisma Zod Generator?**
-  
-</div>
+## ✨ Why Choose Prisma Zod Generator?
 
 <table>
   <tr>
     <td align="center" width="25%">
-      <img src="https://img.shields.io/badge/🚀-Zero_Config-blue?style=for-the-badge" alt="Zero Config">
-      <br><strong>Works instantly</strong><br><em>Sensible defaults included</em>
+      <img src="https://img.shields.io/badge/🚀-Zero_Config-blue?style=for-the-badge" alt="Zero Config"><br>
+      <strong>Works instantly</strong><br><em>Sensible defaults included</em>
     </td>
     <td align="center" width="25%">
-      <img src="https://img.shields.io/badge/🔄-Auto_Generated-green?style=for-the-badge" alt="Auto Generated">
-      <br><strong>Always in sync</strong><br><em>Updates with schema changes</em>
+      <img src="https://img.shields.io/badge/🔄-Auto_Generated-green?style=for-the-badge" alt="Auto Generated"><br>
+      <strong>Always in sync</strong><br><em>Updates with schema changes</em>
     </td>
     <td align="center" width="25%">
-      <img src="https://img.shields.io/badge/🛡️-Type_Safe-purple?style=for-the-badge" alt="Type Safe">
-      <br><strong>100% TypeScript</strong><br><em>Catch errors at compile time</em>
+      <img src="https://img.shields.io/badge/🛡️-Type_Safe-purple?style=for-the-badge" alt="Type Safe"><br>
+      <strong>100% TypeScript</strong><br><em>Catch errors at compile time</em>
     </td>
     <td align="center" width="25%">
-      <img src="https://img.shields.io/badge/🎯-Comprehensive-orange?style=for-the-badge" alt="Comprehensive">
-      <br><strong>Full CRUD coverage</strong><br><em>All Prisma operations included</em>
+      <img src="https://img.shields.io/badge/🎯-Comprehensive-orange?style=for-the-badge" alt="Comprehensive"><br>
+      <strong>Full CRUD coverage</strong><br><em>All Prisma operations included</em>
     </td>
   </tr>
   <tr>
     <td align="center">
-      <img src="https://img.shields.io/badge/⚙️-Configurable-red?style=for-the-badge" alt="Configurable">
-      <br><strong>Highly customizable</strong><br><em>Adapt to your needs</em>
+      <img src="https://img.shields.io/badge/⚙️-Configurable-red?style=for-the-badge" alt="Configurable"><br>
+      <strong>Highly customizable</strong><br><em>Adapt to your needs</em>
     </td>
     <td align="center">
-      <img src="https://img.shields.io/badge/📦-Lightweight-yellow?style=for-the-badge" alt="Lightweight">
-      <br><strong>Minimal footprint</strong><br><em>Fast generation & runtime</em>
+      <img src="https://img.shields.io/badge/📦-Lightweight-yellow?style=for-the-badge" alt="Lightweight"><br>
+      <strong>Minimal footprint</strong><br><em>Fast generation & runtime</em>
     </td>
     <td align="center">
-      <img src="https://img.shields.io/badge/🗄️-Multi_DB-cyan?style=for-the-badge" alt="Multi Database">
-      <br><strong>All databases</strong><br><em>PostgreSQL, MySQL, MongoDB+</em>
+      <img src="https://img.shields.io/badge/🗄️-Multi_DB-cyan?style=for-the-badge" alt="Multi Database"><br>
+      <strong>All databases</strong><br><em>PostgreSQL, MySQL, MongoDB+</em>
     </td>
     <td align="center">
-      <img src="https://img.shields.io/badge/🎨-Flexible-pink?style=for-the-badge" alt="Flexible">
-      <br><strong>Your way</strong><br><em>Custom paths & options</em>
+      <img src="https://img.shields.io/badge/🎨-Flexible-pink?style=for-the-badge" alt="Flexible"><br>
+      <strong>Your way</strong><br><em>Custom paths & options</em>
     </td>
   </tr>
 </table>
 
-## 🚀 Quick Start
-
-### Installation
-
-```bash
-# NPM
-npm install prisma-zod-generator
-
-# Yarn
-yarn add prisma-zod-generator
-
-# PNPM  
-pnpm add prisma-zod-generator
-```
-
-### Setup
-
-1. **Star this repo** 😉
-
-2. **Add the generator to your Prisma schema:**
-
-```prisma
-generator zod {
-  provider           = "prisma-zod-generator"
-  output             = "./generated/schemas"   // default: "./generated"
-  isGenerateSelect   = false                   // default: false
-  isGenerateInclude  = false                   // default: false
-  exportTypedSchemas = true                    // default: true
-  exportZodSchemas   = true                    // default: true  
-  typedSchemaSuffix  = "Schema"                // default: "Schema"
-  zodSchemaSuffix    = "ZodSchema"             // default: "ZodSchema"
-}
-```
-
-3. **Enable strict mode in `tsconfig.json`** (required by Zod):
+### 🔄 Upgrading
 
-```json
-{
-  "compilerOptions": {
-    "strict": true,
-  }
-}
-```
+The latest stable version maintains full API compatibility. Requirements:
+- Node.js 18+
+- Prisma 6.12.0+
+- Zod 4.0.5+
 
-4. **Generate your Zod schemas:**
+Update and regenerate:
 
 ```bash
+npm update prisma-zod-generator
 npx prisma generate
 ```
 
-
 ## 📋 Generated Output
 
-For the following schema:
+<details>
+<summary><strong>📁 File Structure Overview</strong></summary>
+
+For this Prisma schema:
 
 ```prisma
 model User {
@@ -224,15 +208,10 @@ model User {
 
 model Post {
   id        Int      @id @default(autoincrement())
-  createdAt DateTime @default(now())
-  updatedAt DateTime @updatedAt
   title     String
   content   String?
-  published Boolean  @default(false)
-  viewCount Int      @default(0)
   author    User?    @relation(fields: [authorId], references: [id])
   authorId  Int?
-  likes     BigInt
 }
 ```
 
@@ -252,322 +231,189 @@ The generator creates:
 └── 📄 index.ts         # Barrel exports
 ```
 
-## 🚀 Dual Schema Export Strategy - Breakthrough Feature!
+</details>
+
+---
+
+## :rocket: Dual Schema Export Strategy - Breakthrough Feature!
 
-### 🎯 **Solving the Type Safety vs Method Availability Trade-off**
+### 🎯 Solving the Type Safety vs Method Availability Trade-off
 
-This generator implements a **revolutionary dual export strategy** that solves a fundamental limitation in TypeScript + Zod integration!
+This generator implements a dual export strategy that gives you both perfect Prisma typing and full Zod method support.
 
 #### The Problem
 With Zod schemas, you traditionally face a choice:
-- **Type-Safe**: `z.ZodType<Prisma.Type>` gives perfect inference but breaks Zod methods (`.extend()`, `.omit()`, `.merge()`)
-- **Method-Friendly**: Pure Zod schemas support all methods but lose perfect type binding
+- Type-safe: `z.ZodType<Prisma.Type>` gives perfect inference but restricts Zod method chaining
+- Method-friendly: Pure Zod schemas support all methods but lose perfect type binding
 
-#### Our Solution: **Export Both Versions!**
+#### Our Solution: Export Both Versions
 
-```typescript
-// Perfect type safety (no methods)
+```ts
+// Perfect type safety (no Zod method chaining)
 export const PostFindManySchema: z.ZodType<Prisma.PostFindManyArgs> = schema;
 
-// Full method availability (good inference)  
+// Full method availability (great inference)
 export const PostFindManyZodSchema = schema;
 ```
 
 #### Usage Examples
 
-**🔒 Type-Safe Version** (Perfect Prisma integration):
-```typescript
+Type-safe version (perfect Prisma integration):
+
+```ts
 import { PostFindManySchema } from './generated/schemas/findManyPost.schema';
 
-// Perfect type inference
 type FindManyArgs = z.infer<typeof PostFindManySchema>; // Prisma.PostFindManyArgs
 
-// Runtime validation
 const validatedInput = PostFindManySchema.parse(queryParams);
-const posts = await prisma.post.findMany(validatedInput); // ✅ Perfect type safety
+const posts = await prisma.post.findMany(validatedInput);
 ```
 
-**🔧 Method-Friendly Version** (Full Zod capabilities):
-```typescript
+Method-friendly version (full Zod capabilities):
+
+```ts
 import { PostFindManyZodSchema } from './generated/schemas/findManyPost.schema';
 
-// All Zod methods work perfectly!
 const customSchema = PostFindManyZodSchema
-  .extend({ customField: z.string() })     // ✅ Works!
-  .omit({ take: true })                   // ✅ Works!
-  .merge(otherSchema);                    // ✅ Works!
+  .extend({ customField: z.string() })
+  .omit({ take: true })
+  .merge(otherSchema);
 
-const partialSchema = PostFindManyZodSchema.partial(); // ✅ Works!
+const partialSchema = PostFindManyZodSchema.partial();
 ```
 
 #### Configuration Options
 
-Configure dual exports to match your needs:
-
 ```prisma
 generator zod {
-  provider          = "prisma-zod-generator"
-  output            = "./generated/schemas"
-  
-  // Dual export configuration
-  exportTypedSchemas = true        # Export z.ZodType<Prisma.Type> versions
-  exportZodSchemas   = true        # Export pure Zod versions
-  typedSchemaSuffix  = "Schema"    # Suffix for typed versions
-  zodSchemaSuffix    = "ZodSchema" # Suffix for method-friendly versions
+  provider           = "prisma-zod-generator"
+  output             = "./generated/schemas"
+  exportTypedSchemas = true        // Export z.ZodType<Prisma.Type> versions
+  exportZodSchemas   = true        // Export pure Zod versions
+  typedSchemaSuffix  = "Schema"    // Suffix for typed versions
+  zodSchemaSuffix    = "ZodSchema" // Suffix for method-friendly versions
 }
 ```
 
-#### Generated Schema Examples
-
-**For `PostFindManySchema`**:
-```typescript
-// Type-safe version (perfect inference, no methods)
-export const PostFindManySchema: z.ZodType<Prisma.PostFindManyArgs> = z.object({
-  select: PostSelectSchema.optional(),
-  where: PostWhereInputObjectSchema.optional(),
-  take: z.number().optional(),
-  // ...
-}).strict();
-
-// Method-friendly version (full methods, good inference)
-export const PostFindManyZodSchema = z.object({
-  select: PostSelectSchema.optional(),
-  where: PostWhereInputObjectSchema.optional(), 
-  take: z.number().optional(),
-  // ...
-}).strict();
-```
-
-**For inlined Select schemas**:
-```typescript
-// Type-safe select schema
-export const PostSelectSchema: z.ZodType<Prisma.PostSelect> = z.object({
-  id: z.boolean().optional(),
-  title: z.boolean().optional(),
-  author: z.union([z.boolean(), z.lazy(() => UserArgsObjectSchema)]).optional(),
-}).strict();
-
-// Method-friendly select schema
-export const PostSelectZodSchema = z.object({
-  id: z.boolean().optional(),
-  title: z.boolean().optional(), 
-  author: z.union([z.boolean(), z.lazy(() => UserArgsObjectSchema)]).optional(),
-}).strict();
-```
-
-#### When to Use Which Version
-
-| Use Case | Recommended Version | Why |
-|----------|-------------------|-----|
-| **API Validation** | `PostFindManySchema` | Perfect type safety with Prisma |
-| **Schema Composition** | `PostFindManyZodSchema` | Need `.extend()`, `.omit()`, `.merge()` |
-| **Runtime Validation** | Either | Identical runtime behavior |
-| **Type Inference** | Either | Both provide excellent IntelliSense |
-
-#### Competitive Advantage
-
-This breakthrough solves what other generators describe as an **unsolvable trade-off**:
-
-- ✅ **Perfect Type Safety**: Full Prisma type integration
-- ✅ **Full Method Support**: All Zod methods available
-- ✅ **Zero Runtime Overhead**: Both versions are identical at runtime
-- ✅ **Developer Choice**: Pick the right tool for each use case
-- ✅ **Future Proof**: Configurable for different preferences
-
-**You get BOTH worlds - no compromises!** 🎉
-
-### 🎓 **How to Choose Your Configuration**
-
-The dual export system gives you complete control. Here are common configurations and when to use them:
+#### Configuration Scenarios
 
-#### 📋 **Configuration Scenarios**
+Type-safe only:
 
-**🔒 Type-Safe Only** (Perfect Prisma Integration):
 ```prisma
 generator zod {
   provider           = "prisma-zod-generator"
-  exportTypedSchemas = true     # Keep type-safe versions
-  exportZodSchemas   = false    # Skip method-friendly versions
+  exportTypedSchemas = true
+  exportZodSchemas   = false
 }
 ```
-**Best for:** API validation, runtime type checking, perfect Prisma integration
-**You get:** `PostFindManySchema: z.ZodType<Prisma.PostFindManyArgs>`
 
-**🔧 Method-Friendly Only** (Full Zod Capabilities):
+Method-friendly only:
+
 ```prisma
 generator zod {
-  provider           = "prisma-zod-generator"  
-  exportTypedSchemas = false    # Skip type-safe versions
-  exportZodSchemas   = true     # Keep method-friendly versions
+  provider           = "prisma-zod-generator"
+  exportTypedSchemas = false
+  exportZodSchemas   = true
 }
 ```
-**Best for:** Schema composition, form validation, custom transformations
-**You get:** `PostFindManyZodSchema` (supports `.extend()`, `.omit()`, `.merge()`)
 
-**🎯 Both Versions** (Maximum Flexibility):
+Both versions:
+
 ```prisma
 generator zod {
   provider           = "prisma-zod-generator"
-  exportTypedSchemas = true     # Include type-safe versions  
-  exportZodSchemas   = true     # Include method-friendly versions
+  exportTypedSchemas = true
+  exportZodSchemas   = true
 }
 ```
-**Best for:** Teams with mixed use cases, gradual migration, maximum flexibility
-**You get:** Both `PostFindManySchema` AND `PostFindManyZodSchema`
 
-**🎨 Custom Naming** (Your Preferred Style):
+Custom naming:
+
 ```prisma
 generator zod {
   provider           = "prisma-zod-generator"
   exportTypedSchemas = true
   exportZodSchemas   = true
-  typedSchemaSuffix  = "Args"      # PostFindManyArgs
-  zodSchemaSuffix    = "Validator" # PostFindManyValidator
+  typedSchemaSuffix  = "Args"
+  zodSchemaSuffix    = "Validator"
 }
 ```
 
-#### 🚀 **Quick Migration Guide**
+Pro tips:
 
-**From Other Generators:**
-1. Start with `exportTypedSchemas = true, exportZodSchemas = false`
-2. Test your existing API validation code - should work perfectly
-3. Optionally enable `exportZodSchemas = true` for new schema composition needs
+- Smaller bundles: use a single export mode
+- Team consistency: choose one naming convention and stick with it
+- Gradual adoption: start with type-safe schemas, add method-friendly as needed
+- IDE performance: fewer exports -> faster IntelliSense in huge projects
 
-**New Projects:**
-- Use **Type-Safe Only** for API endpoints and data validation
-- Use **Both Versions** if you need schema composition AND perfect typing
-- Use **Method-Friendly Only** for form validation and schema transformations
+---
 
-#### 💡 **Pro Tips**
+## :package: Version Compatibility
 
-- **Smaller bundles**: Use single export mode (`exportZodSchemas = false` OR `exportTypedSchemas = false`)
-- **Team consistency**: Choose one naming convention and stick with it
-- **Gradual adoption**: Start with type-safe schemas, add method-friendly as needed
-- **IDE performance**: Fewer exports = faster IntelliSense in large projects
+<details>
+<summary><strong>🔄 Supported Versions & Migration Guide</strong></summary>
 
-## ⚙️ Configuration Options
+### Current Requirements
 
-| Option | Description | Type | Default |
-|--------|-------------|------|---------|
-| `output` | Output directory for generated files | `string` | `"./generated"` |
-| `isGenerateSelect` | Generate Select-related schemas | `boolean` | `false` |
-| `isGenerateInclude` | Generate Include-related schemas | `boolean` | `false` |
-| `exportTypedSchemas` | Export z.ZodType versions (type-safe) | `boolean` | `true` |
-| `exportZodSchemas` | Export pure Zod versions (method-friendly) | `boolean` | `true` |  
-| `typedSchemaSuffix` | Suffix for typed schemas | `string` | `"Schema"` |
-| `zodSchemaSuffix` | Suffix for Zod schemas | `string` | `"ZodSchema"` |
+| Component | Version | Status |
+|-----------|---------|---------|
+| **Node.js** | 18+ | ✅ Required |
+| **Prisma** | 6.12.0+ | ✅ Recommended |
+| **Zod** | 4.0.5+ | ✅ Required |
+| **TypeScript** | 5.8+ | ✅ Recommended |
 
-### Example Configuration
+### Prisma Client Generator Support
 
+Both legacy and new ESM-compatible generators are supported:
+
+#### Legacy Generator (Existing Projects)
 ```prisma
-generator zod {
-  provider          = "prisma-zod-generator"
-  output            = "./src/schemas"
-  isGenerateSelect  = true
-  isGenerateInclude = true
+generator client {
+  provider = "prisma-client-js"
 }
 ```
 
-## 🔧 Advanced Usage
-
-### Model Customizations
-
-Hide specific models from generation:
-
+#### New ESM Generator (Prisma 6.12.0+)
 ```prisma
-/// @@Gen.model(hide: true)
-model InternalLog {
-  id        Int      @id @default(autoincrement())
-  message   String
-  createdAt DateTime @default(now())
+generator client {
+  provider = "prisma-client"
+  output = "./src/generated/client"
+  runtime = "nodejs"
+  moduleFormat = "esm"
+  generatedFileExtension = "ts"
+  importFileExtension = "ts"
 }
 ```
 
-### Database Provider Support
-
-The generator supports all Prisma database providers:
-
-- **PostgreSQL** - Complete support including advanced types
-- **MySQL** - Full compatibility with all MySQL features  
-- **MongoDB** - Native MongoDB schema generation
-- **SQLite** - Perfect for development and testing
-- **SQL Server** - Enterprise-grade support
-- **CockroachDB** - Distributed database support
+### Migration Guide
 
-## 📚 Examples
+**Existing Projects**: No changes needed - continue using `prisma-client-js`
 
-### Express.js API Validation
+**New Projects**: Consider the new `prisma-client` generator for ESM support
 
-```typescript
-import express from 'express';
-import { PostCreateOneSchema, UserFindManySchema } from './generated/schemas';
+</details>
 
-const app = express();
+---
 
-// Create post with validation
-app.post('/posts', async (req, res) => {
-  try {
-    const data = PostCreateOneSchema.parse(req.body);
-    const post = await prisma.post.create(data);
-    res.json(post);
-  } catch (error) {
-    if (error instanceof z.ZodError) {
-      return res.status(400).json({ errors: error.errors });
-    }
-    res.status(500).json({ error: 'Internal server error' });
-  }
-});
+## 📚 Core Examples
 
-// Query with validation
-app.get('/users', async (req, res) => {
-  const query = UserFindManySchema.parse(req.query);
-  const users = await prisma.user.findMany(query);
-  res.json(users);
-});
-```
+<details>
+<summary><strong>🎯 Essential Usage Patterns</strong></summary>
 
-### Next.js API Routes
+### API Validation
 
 ```typescript
-// pages/api/users.ts
-import type { NextApiRequest, NextApiResponse } from 'next';
-import { UserCreateOneSchema } from '../../generated/schemas';
-
-export default async function handler(req: NextApiRequest, res: NextApiResponse) {
-  if (req.method === 'POST') {
-    try {
-      const userData = UserCreateOneSchema.parse(req.body);
-      const user = await prisma.user.create(userData);
-      res.status(201).json(user);
-    } catch (error) {
-      res.status(400).json({ error: error.message });
-    }
-  }
-}
-```
-
-### tRPC Integration
+// Validate input data
+const createUser = UserCreateInputObjectSchema.parse(requestData);
 
-```typescript
-import { z } from 'zod';
-import { PostCreateOneSchema, PostFindManySchema } from './generated/schemas';
+// Validate query parameters
+const findUsers = UserFindManySchema.parse(queryParams);
 
-export const postRouter = router({
-  create: publicProcedure
-    .input(PostCreateOneSchema)
-    .mutation(({ input }) => {
-      return prisma.post.create(input);
-    }),
-    
-  list: publicProcedure
-    .input(PostFindManySchema)
-    .query(({ input }) => {
-      return prisma.post.findMany(input);
-    }),
-});
+// Validate update operations
+const updateUser = UserUpdateOneSchema.parse(updateData);
 ```
 
-### React Hook Form Integration
+### Form Validation with React Hook Form
 
 ```typescript
 import { useForm } from 'react-hook-form';
@@ -579,243 +425,1036 @@ function CreateUserForm() {
     resolver: zodResolver(UserCreateInputObjectSchema)
   });
 
-  const onSubmit = async (data) => {
-    const response = await fetch('/api/users', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ data })
-    });
-  };
-
   return (
     <form onSubmit={handleSubmit(onSubmit)}>
       <input {...register('email')} type="email" />
       {errors.email && <span>{errors.email.message}</span>}
-      
-      <input {...register('name')} />
-      {errors.name && <span>{errors.name.message}</span>}
-      
       <button type="submit">Create User</button>
     </form>
   );
 }
 ```
 
-## 🔧 API Reference
-
-### Generated Schema Types
-
-The generator creates the following types of schemas:
-
-#### Operation Schemas
-- **Create Operations**: `ModelCreateOneSchema`, `ModelCreateManySchema`
-- **Read Operations**: `ModelFindManySchema`, `ModelFindUniqueSchema`, `ModelFindFirstSchema`
-- **Update Operations**: `ModelUpdateOneSchema`, `ModelUpdateManySchema`, `ModelUpsertSchema`
-- **Delete Operations**: `ModelDeleteOneSchema`, `ModelDeleteManySchema`
-- **Aggregate Operations**: `ModelAggregateSchema`, `ModelGroupBySchema`
+### Database Operations
 
-#### Input Object Schemas
-- **Create Inputs**: `ModelCreateInputObjectSchema`, `ModelCreateNestedInputObjectSchema`
-- **Update Inputs**: `ModelUpdateInputObjectSchema`, `ModelUpdateNestedInputObjectSchema`
-- **Where Inputs**: `ModelWhereInputObjectSchema`, `ModelWhereUniqueInputObjectSchema`
-- **Order Inputs**: `ModelOrderByInputObjectSchema`
+```typescript
+// Safe database queries with validation
+const searchUsers = async (params: unknown) => {
+  const validatedParams = UserFindManySchema.parse(params);
+  return await prisma.user.findMany(validatedParams);
+};
+
+// Validated mutations
+const createPost = async (data: unknown) => {
+  const validatedData = PostCreateOneSchema.parse(data);
+  return await prisma.post.create(validatedData);
+};
+```
 
-#### Select & Include Schemas (Optional)
-When enabled with `isGenerateSelect: true` and `isGenerateInclude: true`:
-- **Select Schemas**: `ModelSelectObjectSchema`
-- **Include Schemas**: `ModelIncludeObjectSchema`
+</details>
 
-### Schema Naming Convention
+---
 
-All generated schemas follow a consistent naming pattern:
-```
-{ModelName}{Operation}{Type}Schema
-```
+## 🔧 Advanced Features
 
-Examples:
-- `UserCreateOneSchema` - Schema for creating a single user
-- `PostFindManyArgsSchema` - Schema for finding multiple posts with arguments
-- `UserWhereInputObjectSchema` - Schema for user where conditions
+<details>
+<summary><strong>🎯 Configuration System</strong></summary>
 
-## 🔍 Troubleshooting
+Looking for ready-made configs? See the new Recipes catalog in `recipes/` for common setups (single file, models-only, minimal CRUD, tRPC, API result schemas, hide fields, and more).
 
-### Latest Version Information
+### JSON-Based Configuration
 
-**Recent Schema Compilation Fixes**
-- **SortOrderInput schemas**: Fixed unnecessary lazy loading that caused validation issues
-- **Args schemas**: Resolved TypeScript compilation errors for UserArgs, ProfileArgs, etc.
-- **All schemas**: Now compile cleanly without type constraint issues
-- **Full backward compatibility**: No code changes needed when upgrading
+Create `zod-generator.config.json`:
 
-**Generator Support**
-- Both `prisma-client-js` and `prisma-client` generators are fully supported
-- If using the new generator, ensure Prisma 6.12.0+ is installed
-- Clear error messages guide you if no compatible generator is found
+```json
+{
+  "mode": "custom",
+  "output": "./src/generated/zod",
+  "globalExclusions": {
+    "input": ["id", "createdAt", "updatedAt"],
+    "result": [],
+    "pure": ["password", "hashedPassword"]
+  },
+  "variants": {
+    "pure": {
+      "enabled": true,
+      "suffix": ".model",
+      "excludeFields": []
+    },
+    "input": {
+      "enabled": true,
+      "suffix": ".input",
+      "excludeFields": ["id"]
+    },
+    "result": {
+      "enabled": true,
+      "suffix": ".result",
+      "excludeFields": ["password"]
+    }
+  },
+  "models": {
+    "User": {
+      "enabled": true,
+      "operations": ["findMany", "findUnique", "create", "update"],
+      "variants": {
+        "input": {
+          "excludeFields": ["role", "permissions"]
+        }
+      }
+    }
+  }
+}
+```
 
-**Current Requirements**
-- Requires Node.js 18+
-- Requires Prisma 6.12.0+ and Zod 4.0.5+
-- All peer dependencies must be compatible
+### Configuration Modes
 
-**Upgrading to Latest Version**
-- Backup your project before upgrading
-- Update all related dependencies (Prisma, Zod, TypeScript)
-- Re-run `npx prisma generate` after upgrading
-- Test thoroughly in development environment
+```typescript
+// Minimal mode - essential operations only
+const minimalConfig = {
+  mode: "minimal",
+  operations: ["findMany", "findUnique", "create", "update"]
+};
+
+// Full mode - all operations and features
+const fullConfig = {
+  mode: "full",
+  includeAggregations: true,
+  includeGroupBy: true
+};
+```
 
-### Common Issues
+</details>
 
-**Generator compatibility errors**
-- Ensure you have either `prisma-client-js` or `prisma-client` generator in your schema
-- The Zod generator provides clear error messages with examples if no compatible generator is found
-- Both legacy and new generators are supported simultaneously
+<details>
+<summary><strong>🎨 Schema Variants</strong></summary>
 
-**Error: Cannot find module './generated/schemas'**
-- Ensure you've run `npx prisma generate` after adding the generator
-- Check that your output path is correct
+### Multiple Schema Types
 
-**TypeScript errors in generated schemas**
-- Make sure all dependencies are installed and up to date
-- Ensure `strict: true` is enabled in `tsconfig.json`
+Generate different schema variants for various use cases:
 
-**Generated schemas not updating**
-- Run `npx prisma generate` after modifying your schema
-- Check that the generator is properly configured in `schema.prisma`
-- Clear your build cache and regenerate
+```typescript
+// Pure model schemas - exact Prisma model structure
+import { UserModelSchema } from './schemas/User.model';
 
-**Zod validation errors**
-- Ensure you have Zod 4.0.5+ installed for compatibility
-- Check that your input schemas match your Prisma model types
+// Input schemas - for API endpoints and forms
+import { UserInputSchema } from './schemas/User.input';
 
-**Generator fails to run**
-- Ensure you have the correct version installed
-- Check that your `schema.prisma` syntax is valid
-- Verify Node.js version compatibility (18+)
-- Clear node_modules and reinstall dependencies
+// Result schemas - for API responses
+import { UserResultSchema } from './schemas/User.result';
 
-### Performance Considerations
+// Usage examples
+const createUser = UserInputSchema.parse(formData);
+const userResponse = UserResultSchema.parse(dbResult);
+const pureUser = UserModelSchema.parse(prismaModel);
+```
 
-#### Large Schemas
-For projects with many models (50+), consider:
-- Using selective generation with model hiding
-- Splitting schemas into multiple files
-- Implementing lazy loading for schemas
+### Variant Configuration
 
-#### Build Times
-To optimize build performance:
-- Add generated files to `.gitignore`
-- Use parallel builds where possible
-- Consider caching in CI/CD pipelines
+```json
+{
+  "variants": [
+    {
+      "name": "input",
+      "suffix": "Input",
+      "exclude": ["id", "createdAt", "updatedAt"]
+    },
+    {
+      "name": "result",
+      "suffix": "Result", 
+      "exclude": ["password"]
+    },
+    {
+      "name": "public",
+      "suffix": "Public",
+      "exclude": ["password", "email", "internalId"]
+    }
+  ]
+}
+```
 
-### FAQ
+</details>
 
-**Q: Can I customize the generated schema validation rules?**
-A: The schemas are generated based on your Prisma schema constraints. Modify your Prisma model definitions to change validation rules.
+<details>
+<summary><strong>🔍 Field Exclusion System</strong></summary>
 
-**Q: Does this work with Prisma Edge Runtime?**
-A: Yes, the generated schemas are compatible with Prisma Edge Runtime.
+### Global and Model-Specific Exclusions
 
-**Q: Can I use this with databases other than the officially supported ones?**
-A: The generator supports all Prisma-compatible databases. Custom databases should work if Prisma supports them.
+```typescript
+// Configuration-based exclusion
+const config = {
+  globalExclusions: {
+    input: ["id", "createdAt", "updatedAt"],
+    result: ["password", "hashedPassword"],
+    pure: []
+  },
+  models: {
+    User: {
+      variants: {
+        input: { excludeFields: ["role", "permissions"] },
+        result: { excludeFields: ["password", "sessionToken"] }
+      }
+    }
+  }
+};
+```
 
-**Q: How do I handle enum validation?**
-A: Enums are automatically converted to Zod enum schemas and placed in the `enums/` directory.
+### Prisma Schema Exclusions
 
-**Q: Can I exclude certain fields from validation?**
-A: Use Prisma's `@ignore` directive or model-level hiding with `@@Gen.model(hide: true)`.
+```prisma
+model User {
+  id        Int     @id @default(autoincrement())
+  email     String  @unique
+  password  String  // Excluded from result schemas
+  role      String  // Excluded from input schemas
+  /// @@Gen.model(hide: true)  // Hide entire model
+  posts     Post[]
+}
+```
 
-### Getting Help
+</details>
 
-- 🐛 **Bug Reports**: [Create a bug report](https://github.com/omar-dulaimi/prisma-zod-generator/issues/new)
-- 💡 **Feature Requests**: [Request a feature](https://github.com/omar-dulaimi/prisma-zod-generator/issues/new)
-- 💬 **Discussions**: [Join the discussion](https://github.com/omar-dulaimi/prisma-zod-generator/discussions)
+<details>
+<summary><strong>📝 @zod Comment Annotations</strong></summary>
 
-## 🤝 Contributing
+### Inline Validation Rules
+
+Add validation directly in your Prisma schema:
+
+```prisma
+model User {
+  id       Int     @id @default(autoincrement())
+  email    String  @unique /// @zod.email()
+  name     String? /// @zod.min(2).max(50)
+  age      Int?    /// @zod.min(0).max(120)
+  username String  @unique /// @zod.regex(/^[a-zA-Z0-9_]+$/)
+  website  String? /// @zod.url().optional()
+}
+```
+
+Generated schema with validations:
+
+```typescript
+export const UserCreateInputSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(2).max(50).optional(),
+  age: z.number().int().min(0).max(120).optional(),
+  username: z.string().regex(/^[a-zA-Z0-9_]+$/),
+  website: z.string().url().optional()
+});
+```
+
+### Supported @zod Annotations
+
+```prisma
+// String validations
+field String /// @zod.email()
+field String /// @zod.url()
+field String /// @zod.regex(/pattern/)
+field String /// @zod.min(2).max(50)
+
+// Number validations  
+field Int    /// @zod.min(0).max(100)
+field Float  /// @zod.positive()
+
+// Custom validations
+field String /// @zod.custom(z.string().transform(s => s.toLowerCase()))
+```
+
+</details>
+
+<details>
+<summary><strong>🗄️ Multi-Database Provider Support</strong></summary>
+
+### Database-Specific Optimizations
+
+```typescript
+// PostgreSQL - Advanced types supported
+const pgUser = z.object({
+  id: z.number().int(),
+  metadata: z.record(z.unknown()), // JSON type
+  tags: z.array(z.string()),       // Array type
+  balance: z.number()              // Decimal type
+});
+
+// MongoDB - Document structure
+const mongoUser = z.object({
+  id: z.string(),                  // ObjectId as string
+  embedded: z.object({             // Embedded documents
+    profile: z.object({
+      bio: z.string().optional()
+    })
+  }).optional()
+});
+
+// MySQL - Optimized for relational data
+const mysqlUser = z.object({
+  id: z.number().int(),
+  createdAt: z.date(),
+  updatedAt: z.date()
+});
+```
+
+### Supported Providers
+
+- **PostgreSQL** - Full advanced type support
+- **MySQL** - Complete compatibility  
+- **MongoDB** - Native document schemas
+- **SQLite** - Development & testing optimized
+- **SQL Server** - Enterprise features
+- **CockroachDB** - Distributed database support
+
+</details>
+
+<details>
+<summary><strong>🔧 ESM Import Handling</strong></summary>
+
+### Modern ES Module Support
+
+Full ESM compatibility with automatic file extension handling:
+
+```prisma
+generator client {
+  provider = "prisma-client"
+  output   = "./src/generated/client"
+  moduleFormat = "esm"
+  importFileExtension = "js"  # Auto-handled
+}
+```
+
+Generated imports include proper extensions:
+
+```typescript
+import { User } from '../client/index.js';  // Auto-generated
+import { z } from 'zod';
+```
+
+### Import Configuration
+
+```json
+{
+  "esm": {
+    "enabled": true,
+    "fileExtension": ".js",
+    "importExtension": ".js"
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>⚡ Performance Optimization</strong></summary>
+
+### Built-in Optimizations
+
+```typescript
+// Lazy loading for circular references
+const UserSchema = z.lazy(() => z.object({
+  id: z.number().int(),
+  posts: z.array(PostSchema).optional()
+}));
+
+// Selective generation
+const config = {
+  models: {
+    AuditLog: { enabled: false },    // Skip audit tables
+    Migration: { enabled: false },   // Skip migration tables
+    User: {
+      enabled: true,
+      operations: ["findMany", "create", "update"] // Only needed operations
+    }
+  }
+};
+```
+
+### Performance Tips
+
+- Use `minimal` mode for faster generation
+- Exclude unused models and operations
+- Enable lazy loading for complex relationships
+- Cache generated schemas in production
+
+</details>
+
+<details>
+<summary><strong>🔐 API Security & Validation Patterns</strong></summary>
+
+### Input Sanitization
+
+```typescript
+export const sanitizeUserInput = (data: unknown) => {
+  return UserCreateInputSchema
+    .omit({ id: true })           // Remove ID from input
+    .extend({
+      email: z.string().email().toLowerCase() // Normalize email
+    })
+    .parse(data);
+};
+```
+
+### Role-Based Field Filtering
+
+```typescript
+export const getUserForRole = (user: User, role: 'admin' | 'user') => {
+  const baseSchema = UserResultSchema;
+  
+  if (role === 'user') {
+    return baseSchema.omit({ 
+      email: true, 
+      role: true,
+      permissions: true 
+    }).parse(user);
+  }
+  
+  return baseSchema.parse(user);
+};
+```
+
+### Complete API Endpoint Validation
+
+```typescript
+app.post('/users', async (req, res) => {
+  try {
+    const userData = UserCreateInputSchema.parse(req.body);
+    const user = await prisma.user.create({ data: userData });
+    const response = UserResultSchema.parse(user);
+    res.json(response);
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      return res.status(400).json({ 
+        errors: error.errors.map(e => ({
+          field: e.path.join('.'),
+          message: e.message
+        }))
+      });
+    }
+  }
+});
+```
+
+</details>
+
+---
+
+## ⚙️ Configuration
+
+<details>
+<summary><strong>🔧 Configuration Options</strong></summary>
+
+### Basic Configuration
+
+| Option | Description | Type | Default |
+|--------|-------------|------|---------|
+| `output` | Output directory for generated files | `string` | `"./generated"` |
+| `isGenerateSelect` | Generate Select-related schemas | `boolean` | `false` |
+| `isGenerateInclude` | Generate Include-related schemas | `boolean` | `false` |
+| `exportTypedSchemas` | Export z.ZodType versions (type-safe) | `boolean` | `true` |
+| `exportZodSchemas` | Export pure Zod versions (method-friendly) | `boolean` | `true` |  
+| `typedSchemaSuffix` | Suffix for typed schemas | `string` | `"Schema"` |
+| `zodSchemaSuffix` | Suffix for Zod schemas | `string` | `"ZodSchema"` |
+| `useMultipleFiles` | Output multiple files (true) or single bundle (false) | `boolean` | `true` |
+| `singleFileName` | Name of the single-file bundle when `useMultipleFiles=false` | `string` | `"schemas.ts"` |
+| `placeSingleFileAtRoot` | When `useMultipleFiles=false`, place the single file at the generator output root instead of a `schemas/` subfolder | `boolean` | `true` |
+
+### Advanced Configuration
+
+```prisma
+generator zod {
+  provider          = "prisma-zod-generator"
+  output            = "./src/schemas"
+  // File output mode
+  // true  -> multiple files (default)
+  // false -> single file bundle (see singleFileName below)
+  useMultipleFiles  = true
+  // Optional: name of the single-file bundle when useMultipleFiles = false
+  // Defaults to "schemas.ts"
+  singleFileName    = "schemas.ts"
+  // Optional: when useMultipleFiles = false, place the single file at the
+  // generator output root (true) or inside a schemas/ subdir (false)
+  placeSingleFileAtRoot = true
+  isGenerateSelect  = true
+  isGenerateInclude = true
+  config            = "./zod-config.json"
+}
+```
+
+### Model Customizations
+
+```prisma
+/// @@Gen.model(hide: true)
+model InternalLog {
+  id        Int      @id @default(autoincrement())
+  message   String
+  createdAt DateTime @default(now())
+}
+```
+
+### JSON Configuration File
+
+```json
+{
+  "mode": "custom",
+  "output": "./generated/schemas",
+  "relationModel": true,
+  "modelCase": "PascalCase", 
+  "modelSuffix": "Schema",
+  "useMultipleFiles": true,
+  "placeSingleFileAtRoot": true,
+  "createInputTypes": true,
+  "addIncludeType": true,
+  "addSelectType": true,
+  "validateWhereUniqueInput": true,
+  "prismaClientPath": "@prisma/client"
+}
+```
+
+</details>
+
+---
+
+## 📖 API Reference
+
+## ⚙️ Configuration sources, precedence, and availability
+
+This generator accepts configuration from two sources. When the same option is provided in multiple places, the value is resolved using a simple precedence.
+
+### Sources
+
+- Prisma generator block (schema.prisma)
+  - Standard Prisma fields like `output`.
+  - Simple override flags/strings (e.g., `useMultipleFiles`, `singleFileName`, etc.).
+  - Optional `config = "./zod-generator.config.json"` to point to a JSON file.
+- JSON config file (recommended for complex/nested settings)
+  - Full configuration surface, including nested structures like `models` and `variants`.
+  - Can be provided explicitly via `config = "./path.json"` or auto-discovered (e.g., `zod-generator.config.json`, `.zod-generator.json`).
+
+### Precedence (highest → lowest)
+
+1) Prisma generator block options (direct attributes in `generator zod { ... }`)
+2) JSON config file (explicit or auto-discovered)
+3) Built-in defaults (computed based on `mode`, etc.)
+
+Notes and special cases:
+- Output path: The Prisma generator’s `output` always decides where files go. Any `output` set in the JSON config is ignored.
+- Minimal mode: If `mode = "minimal"` (or legacy `minimal = true`), select/include schemas are forcibly disabled and many complex nested inputs are suppressed to speed up generation and shrink output.
+- Legacy flags: `isGenerateSelect` / `isGenerateInclude` (Prisma block) override the newer `addSelectType` / `addIncludeType` (config JSON). Minimal mode will still force them off.
+
+### Option availability matrix
+
+| Option | Prisma generator block | JSON config file | Notes |
+|---|---|---|---|
+| `output` | Yes (authoritative) | Ignored if present | Use the Prisma generator `output` only |
+| `useMultipleFiles` | Yes | Yes | `false` enables strict single-file mode |
+| `singleFileName` | Yes | Yes | File name for the single bundle (default `schemas.ts`) |
+| `placeSingleFileAtRoot` | Yes | Yes | Place single file at output root (true, default) or under `schemas/` (false) |
+| `placeArrayVariantsAtRoot` | Yes | Yes | For array-based variants placement (root vs `variants/`) |
+| `mode` (`full|minimal|custom`) | Yes | Yes | Minimal mode applies opinionated defaults |
+| `pureModels` | Yes | Yes | Generates `models/` set when multi-file; N/A in single-file (content is bundled) |
+| `globalExclusions` | — | Yes | Object keyed by variant (`input`, `result`, `pure`) |
+| `variants` (object-based) | — | Yes | Nested structure; configure `pure/input/result` |
+| `models.*` (per-model) | — | Yes | Nested per-model rules, operations, and variant overrides |
+| `addSelectType` / `addIncludeType` | Yes (as legacy `isGenerateSelect` / `isGenerateInclude`) | Yes | Prisma block flags override the JSON values; minimal mode forces off |
+| `formatGeneratedSchemas` | — | Yes | Formatting can be skipped for speed (default: false) |
+| `config` (path to JSON) | Yes | — | Points to the JSON file; not a config value itself |
+
+Example: Prisma block overrides JSON file
+
+```prisma
+generator zod {
+  provider              = "prisma-zod-generator"
+  output                = "./generated"
+  // Overrides values from the JSON config below
+  useMultipleFiles      = false
+  singleFileName        = "bundle.ts"
+  placeSingleFileAtRoot = true
+  // Load additional (nested) settings from a JSON file
+  config                = "./zod-generator.config.json"
+}
+```
+
+When both sources specify the same simple option (e.g., `useMultipleFiles`), the Prisma block wins. Nested settings (like `models` and `variants`) should live in the JSON file.
+
+### How @zod schema comments fit into precedence
+
+Inline `@zod` comments in your Prisma schema are not a separate “config source,” but they do affect field-level validation and are always respected when that field is generated.
+
+- Scope: Applies only to the field where the comment appears, and only in schemas that include that field (subject to filtering, variants, minimal mode).
+- Merge behavior: Field validation is built by combining pieces. In practice, the chain is composed of the base Zod type plus any optional/nullable handling, any config-driven validations (e.g., variant `additionalValidation`), and your `@zod` comment directives. If multiple validations of the same kind are present, they’re appended in order; the latter call wins when there’s a conflict.
+- Not a global override: `@zod` comments do not override global settings like `output`, `mode`, or file layout; they only enrich the field’s Zod chain.
+- Filtering/minimal mode: If a field or schema is excluded by filters/variants/minimal mode, its comments simply won’t apply because that schema isn’t emitted.
+
+See the “@zod Comment Annotations” section for syntax and examples.
+
+<details>
+<summary><strong>📚 Generated Schema Types</strong></summary>
+
+### Operation Schemas
+
+- **Create Operations**: `ModelCreateOneSchema`, `ModelCreateManySchema`
+- **Read Operations**: `ModelFindManySchema`, `ModelFindUniqueSchema`, `ModelFindFirstSchema`
+- **Update Operations**: `ModelUpdateOneSchema`, `ModelUpdateManySchema`, `ModelUpsertSchema`
+- **Delete Operations**: `ModelDeleteOneSchema`, `ModelDeleteManySchema`
+- **Aggregate Operations**: `ModelAggregateSchema`, `ModelGroupBySchema`
+
+### Input Object Schemas
+
+- **Create Inputs**: `ModelCreateInputObjectSchema`, `ModelCreateNestedInputObjectSchema`
+- **Update Inputs**: `ModelUpdateInputObjectSchema`, `ModelUpdateNestedInputObjectSchema`
+- **Where Inputs**: `ModelWhereInputObjectSchema`, `ModelWhereUniqueInputObjectSchema`
+- **Order Inputs**: `ModelOrderByInputObjectSchema`
+
+### Select & Include Schemas
+
+When enabled with `isGenerateSelect: true` and `isGenerateInclude: true`:
+- **Select Schemas**: `ModelSelectObjectSchema`
+- **Include Schemas**: `ModelIncludeObjectSchema`
+
+### Schema Naming Convention
+
+All generated schemas follow this pattern:
+```
+{ModelName}{Operation}{Type}Schema
+```
+
+Examples:
+- `UserCreateOneSchema` - Schema for creating a single user
+- `PostFindManyArgsSchema` - Schema for finding multiple posts with arguments
+- `UserWhereInputObjectSchema` - Schema for user where conditions
+
+</details>
+
+---
+
+## 🌐 Framework Examples
+
+<details>
+<summary><strong>🚀 Next.js Integration</strong></summary>
+
+### API Routes
+
+```typescript
+// pages/api/users.ts
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { UserCreateOneSchema } from '../../generated/schemas';
+
+export default async function handler(req: NextApiRequest, res: NextApiResponse) {
+  if (req.method === 'POST') {
+    try {
+      const userData = UserCreateOneSchema.parse(req.body);
+      const user = await prisma.user.create(userData);
+      res.status(201).json(user);
+    } catch (error) {
+      res.status(400).json({ error: error.message });
+    }
+  }
+}
+```
+
+### App Router (Next.js 13+)
+
+```typescript
+// app/api/users/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { UserCreateOneSchema } from '@/generated/schemas';
+
+export async function POST(request: NextRequest) {
+  try {
+    const body = await request.json();
+    const userData = UserCreateOneSchema.parse(body);
+    const user = await prisma.user.create(userData);
+    return NextResponse.json(user);
+  } catch (error) {
+    return NextResponse.json({ error: error.message }, { status: 400 });
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>⚡ tRPC Integration</strong></summary>
+
+```typescript
+import { z } from 'zod';
+import { PostCreateOneSchema, PostFindManySchema } from './generated/schemas';
+
+export const postRouter = router({
+  create: publicProcedure
+    .input(PostCreateOneSchema)
+    .mutation(({ input }) => {
+      return prisma.post.create(input);
+    }),
+    
+  list: publicProcedure
+    .input(PostFindManySchema)
+    .query(({ input }) => {
+      return prisma.post.findMany(input);
+    }),
+});
+```
+
+</details>
+
+<details>
+<summary><strong>🛠️ Fastify Integration</strong></summary>
+
+```typescript
+import fastify from 'fastify';
+import { UserCreateOneSchema } from './generated/schemas';
+
+const server = fastify();
 
-Contributions are welcome! Here's how you can help:
+server.post('/users', {
+  schema: {
+    body: UserCreateOneSchema
+  }
+}, async (request, reply) => {
+  const user = await prisma.user.create(request.body);
+  return user;
+});
+```
+
+</details>
+
+<details>
+<summary><strong>🌐 Express.js Integration</strong></summary>
+
+```typescript
+import express from 'express';
+import { UserCreateOneSchema, UserFindManySchema } from './generated/schemas';
+
+const app = express();
+
+// Create user with validation
+app.post('/users', async (req, res) => {
+  try {
+    const data = UserCreateOneSchema.parse(req.body);
+    const user = await prisma.user.create(data);
+    res.json(user);
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      return res.status(400).json({ errors: error.errors });
+    }
+    res.status(500).json({ error: 'Internal server error' });
+  }
+});
+
+// Query with validation
+app.get('/users', async (req, res) => {
+  const query = UserFindManySchema.parse(req.query);
+  const users = await prisma.user.findMany(query);
+  res.json(users);
+});
+```
+
+</details>
+
+---
+
+## 🧪 Testing & Development
+
+<details>
+<summary><strong>🔬 Testing Infrastructure</strong></summary>
+
+### Test Suite Overview
+
+We maintain **enterprise-grade testing standards** with comprehensive coverage:
+
+#### 📊 **Test Statistics**
+- **📊 80+ Tests Passing** - Comprehensive validation across all features
+- **🔍 5,239 Schemas Validated** - Massive multi-provider testing
+- **✅ 100% TypeScript Compilation** - Zero compilation errors guaranteed
+- **🛡️ Zero ESLint Issues** - Clean, maintainable code quality
+
+#### 📋 **Test Categories**
+
+```bash
+# Core infrastructure tests
+npm run test:core                    # Configuration & integration tests
+npm run test:esm                     # ESM import handling tests
+npm run test:comprehensive           # Multi-provider schema validation
+
+# Feature-specific tests
+npm run test:config                  # Configuration system validation
+npm run test:variants               # Schema variant generation
+npm run test:filtering              # Model/field filtering logic
+npm run test:pure-models            # Pure model schema generation
+npm run test:result-schemas         # Result schema validation
+npm run test:zod-comments           # @zod comment parsing
+npm run test:field-exclusion        # Field exclusion system
+
+# Advanced testing
+npm run test:integration            # Full generation pipeline tests
+npm run test:multi-provider         # All database provider validation
+npm run test:performance            # Schema generation performance
+npm run test:coverage               # Code coverage analysis
+```
+
+</details>
+
+<details>
+<summary><strong>🧪 Testing Integration</strong></summary>
+
+### Schema Testing Utilities
+
+```typescript
+import { SchemaTestUtils } from './test-utils';
+
+// Validate schema structure
+SchemaTestUtils.testValidData(UserCreateInputSchema, {
+  email: 'test@example.com',
+  name: 'Test User'
+});
+
+// Test boundary conditions
+SchemaTestUtils.testBoundaryValues(UserCreateInputSchema, [
+  { value: { email: 'invalid-email' }, shouldPass: false },
+  { value: { name: 'x'.repeat(51) }, shouldPass: false },
+  { value: { name: 'Valid Name' }, shouldPass: true }
+]);
+
+// Performance testing
+const performance = SchemaTestUtils.performanceTest(
+  UserCreateInputSchema,
+  validUserData,
+  1000 // iterations
+);
+console.log(`Avg validation time: ${performance.avgTime}ms`);
+```
 
 ### Development Setup
 
-1. **Fork and clone the repository**
 ```bash
+# Clone and setup
 git clone https://github.com/your-username/prisma-zod-generator.git
 cd prisma-zod-generator
+npm install
+
+# Development build
+npm run gen-example
+
+# Run tests
+npm test
+
+# Code quality
+npm run lint      # Check and fix linting issues
+npm run format    # Format code with Prettier
 ```
 
-2. **Install dependencies**
+</details>
+
+<details>
+<summary><strong>📈 Multi-Database Provider Validation</strong></summary>
+
+Our test suite validates schemas across **6 database providers**:
+
+| Provider | Schemas Validated | Status |
+|----------|------------------|---------|
+| **PostgreSQL** | 1,020 schemas | ✅ |
+| **MySQL** | 1,326 schemas | ✅ |
+| **MongoDB** | 855 schemas | ✅ |
+| **SQLite** | 1,409 schemas | ✅ |
+| **SQL Server** | 622 schemas | ✅ |
+| **Default** | Additional schemas | ✅ |
+
+</details>
+
+---
+
+## 🔍 Troubleshooting
+
+<details>
+<summary><strong>🚨 Common Issues & Solutions</strong></summary>
+
+### Generator Compatibility Errors
+
+**Issue**: Cannot find compatible Prisma generator
 ```bash
-npm install
+Error: No compatible Prisma client generator found
 ```
 
-3. **Run the development build**
-```bash
-npm run gen-example
+**Solution**: Ensure you have a supported generator in your schema:
+```prisma
+generator client {
+  provider = "prisma-client-js"  // or "prisma-client"
+}
+
+generator zod {
+  provider = "prisma-zod-generator"
+  output   = "./generated/schemas"
+}
 ```
 
-4. **Run tests**
-```bash
-npm test
+### Module Resolution Errors
+
+**Issue**: `Cannot find module './generated/schemas'`
+
+**Solutions**:
+1. Run `npx prisma generate` after adding the generator
+2. Check that your output path is correct
+3. Verify the generator completed successfully
+
+### TypeScript Compilation Errors
+
+**Issue**: Generated schemas have TypeScript errors
+
+**Solutions**:
+1. Enable strict mode in `tsconfig.json`:
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+  }
+}
+```
+2. Update dependencies: `npm update prisma-zod-generator prisma zod`
+3. Clear build cache and regenerate
+
+### Generation Performance Issues
+
+**Issue**: Slow generation for large schemas
+
+**Solutions**:
+1. Use minimal mode:
+```json
+{
+  "mode": "minimal",
+  "models": {
+    "AuditLog": { "enabled": false },
+    "Migration": { "enabled": false }
+  }
+}
 ```
+2. Exclude unnecessary operations
+3. Enable selective model generation
+
+</details>
 
-### Testing
+<details>
+<summary><strong>💡 Performance Optimization Tips</strong></summary>
 
-We have comprehensive tests covering:
-- **Unit Tests**: Core transformation logic
-- **Integration Tests**: End-to-end schema generation
-- **Multi-Provider Tests**: All database providers
-- **Performance Tests**: Large schema handling
+### Large Schema Optimization
+
+For projects with 50+ models:
+- Use selective generation with model hiding
+- Split schemas into multiple files  
+- Implement lazy loading for schemas
+- Consider minimal mode for faster builds
+
+### Build Time Optimization
+
+```json
+{
+  "mode": "minimal",
+  "models": {
+    "User": {
+      "operations": ["findMany", "create", "update"]
+    }
+  }
+}
+```
+
+### Production Deployment
+
+```typescript
+// Environment-specific configuration
+const productionConfig = {
+  mode: 'minimal',
+  globalExclusions: {
+    result: ['password', 'sessionToken', 'internalNotes']
+  }
+};
+```
+
+</details>
+
+<details>
+<summary><strong>❓ Frequently Asked Questions</strong></summary>
+
+**Q: Can I customize the generated validation rules?**  
+A: Modify your Prisma schema with `@zod` comments or use configuration options to customize validation.
+
+**Q: Does this work with Prisma Edge Runtime?**  
+A: Yes, generated schemas are compatible with Prisma Edge Runtime.
+
+**Q: How do I handle circular references?**  
+A: The generator automatically uses lazy loading for circular relationships.
+
+**Q: Can I exclude certain fields from validation?**  
+A: Yes, use the `globalExclusions` or model-specific `excludeFields` configuration.
+
+**Q: How do I handle enum validation?**  
+A: Enums are automatically converted to Zod enum schemas in the `enums/` directory.
+
+</details>
+
+---
+
+## 🤝 Contributing
+
+<details>
+<summary><strong>🛠️ Development Guidelines</strong></summary>
+
+
+<details>
+<summary><strong>🚀 Release Process</strong></summary>
+
+This project uses semantic versioning and automated releases:
+
+- Patch: Bug fixes and small improvements
+- Minor: New features and enhancements
+- Major: Breaking changes
+
+Helpful commands:
 
-Run specific test suites:
 ```bash
-npm run test:basic           # Basic functionality
-npm run test:multi           # Multi-provider testing  
-npm run test:coverage        # Coverage reports
-npm run test:comprehensive   # Full test suite
+npm run prerelease   # Build, type-check, lint
+npm run release:dry  # Preview the next release
 ```
 
-### Contribution Guidelines
+</details>
+### Contribution Process
 
 1. **Create an issue** for bugs or feature requests
-2. **Follow the existing code style** (ESLint + Prettier)
-3. **Add tests** for new functionality
-4. **Update documentation** as needed
-5. **Submit a pull request** with a clear description
+2. **Fork and clone** the repository  
+3. **Follow existing code style** (ESLint + Prettier)
+4. **Add comprehensive tests** for new functionality
+5. **Update documentation** as needed
+6. **Submit a pull request** with clear description
 
-### Code Style
+### Code Quality Standards
 
-We use ESLint and Prettier for consistent code formatting:
 ```bash
 npm run lint      # Check and fix linting issues
 npm run format    # Format code with Prettier
+npm test          # Run comprehensive test suite
 ```
 
-### Release Process
+### Testing Requirements
 
-This project uses semantic versioning and automated releases:
-- **Patch**: Bug fixes and small improvements
-- **Minor**: New features and enhancements  
-- **Major**: Breaking changes
+When contributing new features:
+1. **Write tests first** - TDD approach
+2. **Test all edge cases** - Comprehensive scenarios  
+3. **Validate across providers** - Multi-database compatibility
+4. **Performance testing** - Ensure scalability
+5. **Integration testing** - End-to-end validation
+
+</details>
+
+---
 
 ## 📄 License
 
 This project is licensed under the [MIT License](LICENSE).
 
+---
+
 ## 🔗 Related Projects
 
 - [prisma-trpc-generator](https://github.com/omar-dulaimi/prisma-trpc-generator) - Generate tRPC routers from Prisma schema
 - [Prisma](https://github.com/prisma/prisma) - Database toolkit and ORM
 - [Zod](https://github.com/colinhacks/zod) - TypeScript-first schema validation
 
-## 🙏 Acknowledgments
-
-- [Prisma](https://github.com/prisma/prisma) - Modern database toolkit
-- [Zod](https://github.com/colinhacks/zod) - TypeScript-first schema validation
-- All our [contributors](https://github.com/omar-dulaimi/prisma-zod-generator/graphs/contributors)
-
----
-
-<br>
-
 ---
 
 <div align="center">
@@ -828,23 +1467,6 @@ This project is licensed under the [MIT License](LICENSE).
   
   <br><br>
   
-  <table>
-    <tr>
-      <td align="center">
-        <img src="https://img.shields.io/badge/💎-Latest_Stable-success?style=for-the-badge&logo=npm" alt="Stable">
-        <br>
-        <code>v1.0.0</code>
-      </td>
-      <td align="center">
-        <img src="https://img.shields.io/badge/📦-Legacy_Version-lightgrey?style=for-the-badge&logo=archive" alt="Legacy">
-        <br>
-        <code>v0.8.13</code>
-      </td>
-    </tr>
-  </table>
-  
-  <br>
-  
   <p>
     <strong>Made with ❤️ by</strong>
     <a href="https://github.com/omar-dulaimi">
@@ -854,4 +1476,4 @@ This project is licensed under the [MIT License](LICENSE).
   
   <p><em>⚡ Accelerating Prisma development, one schema at a time</em></p>
   
-</div>
+</div>