@oxog/vld 2.1.0 → 2.2.5

package/README.md

@@ -1,1235 +1,1296 @@
-# VLD - Fast & Lightweight TypeScript Validation Library
-
-[![NPM Version](https://img.shields.io/npm/v/@oxog/vld.svg)](https://www.npmjs.com/package/@oxog/vld) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/) [![Zero Dependencies](https://img.shields.io/badge/Dependencies-0-green.svg)](package.json) [![Test Coverage](https://img.shields.io/badge/Coverage-100%25-brightgreen.svg)](package.json)
-
-VLD is a blazing-fast, type-safe validation library for TypeScript and JavaScript with **Zod-compatible root and subpath APIs**. Built with performance in mind, it provides a simple and intuitive API while maintaining excellent type inference and 27+ language internationalization support.
-
-## Table of Contents
-
-- [Features](#-features)
-- [Performance](#-performance)
-- [Installation](#-installation)
-- [Quick Start](#-quick-start)
-- [API Reference](#-api-reference)
-- [Internationalization (i18n)](#-internationalization-i18n)
-- [Error Handling & Formatting](#%EF%B8%8F-error-handling--formatting)
-- [Advanced Examples](#-advanced-examples)
-- [Why VLD?](#-why-vld)
-- [Codecs - Bidirectional Transformations](#-codecs---bidirectional-transformations)
-- [Plugin System](#-plugin-system)
-- [Result Pattern](#-result-pattern)
-- [CLI Tools](#-cli-tools)
-- [Migrating from Zod](#-migrating-from-zod)
-- [Benchmarks](#-benchmarks)
-- [Contributing](#-contributing)
-- [Links](#-links)
-
-## Features
-
-### Core Features
-- **Blazing Fast**: Optimized for V8 engine with superior performance
-- **Type-Safe**: Full TypeScript support with excellent type inference
-- **Zero Dependencies**: Lightweight with no external dependencies
-- **Tree-Shakeable**: Only import what you need
-- **Composable**: Chain validations for complex schemas
-- **Advanced Error Formatting**: Tree, pretty, and flatten error utilities
-- **Multi-language**: Built-in support for 27+ languages
-- **100% Statement / Branch / Line Coverage**: Rigorously tested with 2160 passing tests
-- **Release-Gated Performance**: CI guards require VLD to stay faster than the latest stable Zod across runtime, startup, and memory benchmarks
-- **Drop-in App Verification**: A real TypeScript fixture is compiled and run once with `zod` and once with built VLD, then normalized runtime output is compared
-
-### Advanced Zod-Compatible Features
-- **Type Coercion**: `v.coerce.string()`, `v.coerce.number()`, `v.coerce.boolean()`, etc.
-- **Advanced Types**: BigInt, Symbol, Tuple, Record, Set, Map validation
-- **Intersection Types**: Combine multiple schemas with intelligent merging
-- **Custom Validation**: `refine()` for custom predicates and validation logic
-- **Data Transformation**: `transform()` for post-validation data transformation
-- **Default Values**: `default()` for handling undefined inputs elegantly
-- **Fallback Handling**: `catch()` for graceful error recovery
-- **Object Utilities**: `pick()`, `omit()`, `extend()` for flexible object schemas
-
-### NEW in v2.0.0 - Modular Architecture
-
-#### Tree-Shakable Mini API
-```typescript
-import { string, number, object, optional } from '@oxog/vld/mini';
-
-const schema = object({
-  name: string().min(1),
-  age: optional(number().positive()),
-});
-```
-- **82% smaller bundles** when using only needed validators
-- Individual factory functions for optimal tree-shaking
-- Full TypeScript support with identical type inference
-
-#### Lazy Locale Loading
-```typescript
-import { setLocaleAsync } from '@oxog/vld/locales';
-await setLocaleAsync('tr'); // Loads Turkish on demand
-```
-- **92% bundle reduction** - Only English bundled by default
-- `preloadLocales()` for SSR/batch loading
-- Full backwards compatibility with `setLocale()`
-
-#### Dual ESM/CJS Build
-- ESM builds for modern bundlers (Vite, esbuild)
-- CJS builds for Node.js and legacy environments
-- Proper `exports` field with conditional exports
-
-### NEW in v1.5.0 - Major Platform Release
-
-#### Plugin System
-- **`definePlugin()`**: Create custom plugins with validators, transforms, and codecs
-- **`usePlugin()`**: Register plugins globally
-- **Plugin Hooks**: Lifecycle hooks for validation events
-- **Custom Validators**: Extend VLD with your own validators
-
-#### Result Pattern
-- **`Ok()`/`Err()`**: Functional error handling
-- **`match()`**: Pattern matching on results
-- **`map()`/`flatMap()`**: Transform results
-- **`tryCatch()`**: Safe function execution
-- **`all()`**: Combine multiple results
-
-#### Event System
-- **`createEmitter()`**: Type-safe event emitter
-- **`createEventBus()`**: Global event bus
-- **Validation Events**: Parse start, success, error, field validation
-
-#### CLI Tools
-- **`vld validate`**: Validate data from command line
-- **`vld benchmark`**: Run performance benchmarks
-- **Colored Output**: Beautiful terminal output with pigment
-
-#### New Validators
-- **`v.discriminatedUnion()`**: Discriminated union types
-- **`v.xor()`**: Exclusive OR validation
-- **`v.file()`**: File upload validation
-- **`v.function()`**: Function validation
-- **`v.custom()`**: Type-safe custom validators
-- **`v.json()`**: JSON string validation with schema
-- **`v.lazy()`**: Recursive schema support
-- **`v.nan()`**: NaN validation
-- **`v.null()`**: Null validation
-- **`v.undefined()`**: Undefined validation
-- **`v.templateLiteral()`**: Template literal types
-
-#### New String Format Validators
-- **`v.hostname()`**: Hostname validation
-- **`v.emoji()`**: Emoji validation
-- **`v.base64()`/`v.base64url()`**: Base64 format validation
-- **`v.hex()`**: Hex string validation
-- **`v.jwt()`**: JWT format validation
-- **`v.nanoid()`/`v.cuid()`/`v.cuid2()`/`v.ulid()`**: ID format validation
-- **`v.mac()`**: MAC address validation
-- **`v.cidrv4()`/`v.cidrv6()`**: CIDR block validation
-- **`v.e164()`**: E.164 phone number validation
-- **`v.hash()`**: Hash validation (md5, sha1, sha256, sha384, sha512)
-- **`v.iso.date()`/`v.iso.time()`/`v.iso.dateTime()`/`v.iso.duration()`**: ISO format validation
-
-#### Enhanced Object Utilities
-- **`v.strictObject()`**: Strict mode object validation
-- **`v.looseObject()`**: Passthrough object validation
-- **`v.partialRecord()`**: Partial record validation
-- **`v.looseRecord()`**: Loose record validation
-- **`v.int()`**: Integer shortcut
-- **`v.int32()`**: 32-bit integer shortcut
-- **`v.nullish()`**: Null or undefined
-- **`v.NEVER`**: NEVER constant for transforms (Zod 4 parity)
-
-### Codec System - Beyond Zod
-- **Bidirectional Transformations**: Full encode/decode support for data conversion
-- **19 Built-in Codecs**: String conversions, date parsing, JSON, URL, binary data
-- **Zod-Compatible**: All `stringToNumber`, `jsonCodec`, `base64ToBytes`, etc.
-- **Async Support**: Both sync and async codec operations
-- **Custom Codecs**: Create your own bidirectional transformations
-- **Type-Safe**: Full TypeScript support with perfect type inference
-
-## Performance
-
-VLD is designed for speed and efficiency with recent optimizations delivering exceptional performance:
-
-### Release-Gated Speed Benchmarks (v2.1.0 vs Zod 4.4.3)
-- Runtime guard: VLD must stay at least 1.2x faster on every guarded hot path and keep at least a 3x average ratio
-- Startup guard: VLD must keep at least 1.1x faster import, 1.25x faster total startup, and 1.25x faster warm parse ratios than Zod
-- Memory guard: VLD must keep at least 2x lower total retained heap, 1.5x higher aggregate throughput, and no guarded case below 1.1x speed
-
-### Recent Local Benchmark Snapshot
-- **52.92x faster** for nullish validation
-- **46.58x faster** for catch validation
-- **27.62x faster** for number validation
-- **14.88x faster** for bigint validation
-- **10.71x faster** for nullable validation
-- **Over 10x faster** average guarded runtime ratio in recent release checks
-
-### Optimizations
-- **110x improvement** in union type validation
-- **Simplified email regex** for maximum performance
-- **Inline type checks** in object validation
-- **Optimized loops** with direct array assignment
-- **SafeParse optimization** to avoid try-catch overhead
-- **Pre-computed keys** with Set for O(1) lookups
-
-### Memory Efficiency
-- **18.13x less memory** for schema creation
-- **6.20x less memory** for union validation
-- **2.81x less memory** for simple string validation
-- **4.85x less memory** overall
-
-### A Note on Real-World Benchmarking
-
-Many validation library benchmarks can be misleading because they often test with **reused schema instances**:
-
-```javascript
-// What benchmarks typically test (unrealistic):
-const schema = z.string();
-for (let i = 0; i < 1000000; i++) {
-  schema.parse(data); // Same instance reused
-}
-
-// What happens in real applications:
-app.post('/api/user', (req, res) => {
-  // New schema created for each request
-  const schema = z.object({
-    email: z.string().email(),
-    age: z.number().min(18)
-  });
-  schema.parse(req.body);
-});
-```
-
-When testing real-world patterns:
-- **Creating new instances**: VLD is **2000x faster** than Zod
-- **Reused instances**: Zod benefits from V8's singleton optimization
-- **Real applications**: Schemas are often created dynamically, where VLD excels
-
-Run `npm run benchmark:truth` to see the real performance difference.
-
-## Installation
-
-```bash
-npm install @oxog/vld
-# or
-yarn add @oxog/vld
-# or
-pnpm add @oxog/vld
-```
-
-## Quick Start
-
-```typescript
-import { v } from '@oxog/vld';
-
-// It is recommended to import as `v` for consistency with Zod's `z`
-// and for a more concise syntax.
-
-// Define a schema
-const userSchema = v.object({
-  name: v.string().min(2),
-  email: v.string().email(),
-  age: v.number().min(18).max(100),
-  isActive: v.boolean()
-});
-
-// Validate data
-const result = userSchema.safeParse({
-  name: 'John Doe',
-  email: 'john@example.com',
-  age: 25,
-  isActive: true
-});
-
-if (result.success) {
-  console.log('Valid user:', result.data);
-} else {
-  console.log('Validation error:', result.error);
-}
-```
-
-For advanced error formatting:
-```typescript
-import { v, VldError, treeifyError, prettifyError, flattenError } from '@oxog/vld';
-```
-
-## API Reference
-
-### Basic Types
-
-```typescript
-v.string()    // String validation
-v.number()    // Number validation
-v.int()       // Integer validation (shortcut)
-v.int32()     // 32-bit integer validation
-v.boolean()   // Boolean validation
-v.bigint()    // BigInt validation
-v.symbol()    // Symbol validation
-v.date()      // Date validation
-v.uint8array()// Uint8Array validation
-v.literal()   // Literal values
-v.enum()      // Enum values (supports TypeScript enums)
-v.any()       // Any type
-v.unknown()   // Unknown type
-v.void()      // Void type
-v.never()     // Never type
-v.null()      // Null type
-v.undefined() // Undefined type
-v.nan()       // NaN type
-```
-
-### Advanced Types
-
-```typescript
-// Collections
-v.array(v.string())                    // Array validation
-v.tuple(v.string(), v.number())        // Fixed-length tuple
-v.record(v.number())                   // Record/dictionary validation
-v.set(v.string())                      // Set validation
-v.map(v.string(), v.number())          // Map validation
-
-// Objects
-v.object({                             // Object schema
-  name: v.string(),
-  age: v.number()
-})
-v.strictObject({...})                  // No extra fields allowed
-v.looseObject({...})                   // Extra fields passed through
-
-// Composition
-v.union(v.string(), v.number())        // Union types
-v.intersection(schemaA, schemaB)       // Intersection types
-v.discriminatedUnion('type', ...)      // Discriminated union
-v.xor(schemaA, schemaB)               // Exclusive OR
-v.optional(v.string())                 // Optional fields
-v.nullable(v.string())                 // Nullable fields
-v.nullish(v.string())                  // Null or undefined
-```
-
-### String Validators
-
-```typescript
-v.string()
-  .min(5)                    // Minimum length
-  .max(10)                   // Maximum length
-  .length(8)                 // Exact length
-  .email()                   // Email format
-  .url()                     // URL format
-  .uuid()                    // UUID format
-  .regex(/pattern/)          // Custom regex
-  .startsWith('prefix')      // String prefix
-  .endsWith('suffix')        // String suffix
-  .includes('substring')     // Contains substring
-  .ip()                      // IP address (v4 or v6)
-  .trim()                    // Trim whitespace
-  .toLowerCase()             // Convert to lowercase
-  .toUpperCase()             // Convert to uppercase
-  .nonempty()               // Non-empty string
-```
-
-### String Format Validators (Top-Level)
-
-```typescript
-v.email()                    // Email validation
-v.uuid()                     // UUID validation
-v.uuid({ version: 'v4' })    // UUID v4 validation
-v.uuidv4()                   // UUID v4 shortcut
-v.hostname()                 // Hostname validation
-v.emoji()                    // Emoji validation
-v.base64()                   // Base64 format
-v.base64url()                // Base64 URL-safe format
-v.hex()                      // Hex string
-v.jwt()                      // JWT format
-v.nanoid()                   // NanoID format
-v.cuid()                     // CUID format
-v.cuid2()                    // CUID2 format
-v.ulid()                     // ULID format
-v.ipv4()                     // IPv4 address
-v.ipv6()                     // IPv6 address
-v.mac()                      // MAC address
-v.cidrv4()                   // IPv4 CIDR block
-v.cidrv6()                   // IPv6 CIDR block
-v.e164()                     // E.164 phone number
-v.hash('sha256')             // Hash validation
-v.iso.date()                 // ISO date format
-v.iso.time()                 // ISO time format
-v.iso.dateTime()             // ISO datetime format
-v.iso.duration()             // ISO duration format
-```
-
-### Number Validators
-
-```typescript
-v.number()
-  .min(0)                    // Minimum value
-  .max(100)                  // Maximum value
-  .int()                     // Integer only
-  .positive()                // Positive numbers
-  .negative()                // Negative numbers
-  .nonnegative()            // >= 0
-  .nonpositive()            // <= 0
-  .finite()                  // Finite numbers
-  .safe()                    // Safe integers
-  .multipleOf(5)            // Multiple of value
-```
-
-### Arrays and Objects
-
-```typescript
-// Arrays
-v.array(v.string())          // Array of strings
-  .min(1)                    // Minimum length
-  .max(10)                   // Maximum length
-  .length(5)                 // Exact length
-  .nonempty()               // Non-empty array
-
-// Objects
-v.object({
-  name: v.string(),
-  age: v.number()
-})
-  .partial()                 // All fields optional
-  .strict()                  // No extra fields
-  .passthrough()             // Allow extra fields
-```
-
-### Composite Types
-
-```typescript
-// Optional
-v.optional(v.string())       // string | undefined
-
-// Nullable
-v.nullable(v.string())       // string | null
-
-// Nullish
-v.nullish(v.string())        // string | null | undefined
-
-// Union
-v.union(v.string(), v.number()) // string | number
-
-// Discriminated Union
-v.discriminatedUnion('type',
-  v.object({ type: v.literal('a'), a: v.string() }),
-  v.object({ type: v.literal('b'), b: v.number() })
-)
-
-// Literal
-v.literal('active')          // 'active'
-
-// Enum
-v.enum('red', 'green', 'blue') // 'red' | 'green' | 'blue'
-```
-
-### Type Coercion
-
-```typescript
-// Coerce strings from various types
-v.coerce.string().parse(123)        // "123"
-v.coerce.string().parse(true)       // "true"
-
-// Coerce numbers from strings/booleans
-v.coerce.number().parse("123")      // 123
-v.coerce.number().parse(true)       // 1
-
-// Coerce booleans from strings/numbers
-v.coerce.boolean().parse("true")    // true
-v.coerce.boolean().parse(1)         // true
-
-// Coerce BigInt from strings/numbers
-v.coerce.bigint().parse("123")      // 123n
-v.coerce.bigint().parse(456)        // 456n
-
-// Coerce Date from strings/timestamps
-v.coerce.date().parse("2023-01-01") // Date object
-v.coerce.date().parse(1672531200000) // Date object
-```
-
-### Object Schema Methods
-
-```typescript
-const userSchema = v.object({
-  name: v.string(),
-  age: v.number(),
-  email: v.string(),
-  role: v.string()
-});
-
-// Pick specific fields
-const publicSchema = userSchema.pick('name', 'age');
-// Type: { name: string; age: number }
-
-// Omit sensitive fields
-const safeSchema = userSchema.omit('email', 'role');
-// Type: { name: string; age: number }
-
-// Extend with new fields
-const extendedSchema = userSchema.extend({
-  isActive: v.boolean(),
-  lastLogin: v.date()
-});
-// Type: { name: string; age: number; email: string; role: string; isActive: boolean; lastLogin: Date }
-```
-
-### Advanced Validation Methods
-
-```typescript
-// Custom validation with refine()
-const positiveNumber = v.number()
-  .refine(n => n > 0, "Number must be positive");
-
-// Data transformation with transform()
-const uppercaseString = v.string()
-  .transform(s => s.toUpperCase());
-
-// Default values for undefined
-const withDefault = v.string().default("fallback");
-withDefault.parse(undefined); // "fallback"
-
-// Catch errors and provide fallback
-const withCatch = v.number().catch(-1);
-withCatch.parse("invalid"); // -1
-
-// Method chaining
-const complexSchema = v.string()
-  .min(3)
-  .transform(s => s.trim())
-  .refine(s => s.includes('@'), 'Must contain @')
-  .default('user@example.com');
-```
-
-### Special Validators
-
-```typescript
-// JSON validator with optional schema
-v.json()                           // Any valid JSON
-v.json(v.object({ name: v.string() }))  // Typed JSON
-
-// Lazy for recursive schemas
-const categorySchema = v.lazy(() =>
-  v.object({
-    name: v.string(),
-    children: v.array(categorySchema).optional()
-  })
-);
-
-// Custom validator
-v.custom({
-  check: (val) => typeof val === 'string' && val.length > 0,
-  message: 'Must be a non-empty string'
-});
-
-// File validator
-v.file()
-  .maxSize(5 * 1024 * 1024)  // 5MB
-  .type(['image/png', 'image/jpeg']);
-
-// Function validator
-v.function()
-  .args(v.string(), v.number())
-  .returns(v.boolean());
-```
-
-### Type Inference
-
-```typescript
-import { v } from '@oxog/vld';
-import type { Infer } from '@oxog/vld';
-
-const schema = v.object({
-  name: v.string(),
-  age: v.number()
-});
-
-// Automatically infer the type
-type User = Infer<typeof schema>;
-// { name: string; age: number }
-```
-
-### Error Formatting Types
-
-```typescript
-import { VldError } from '@oxog/vld';
-import type {
-  VldIssue,           // Individual validation issue
-  VldErrorTree,       // Nested error structure
-  VldFlattenedError   // Flattened error structure
-} from '@oxog/vld';
-```
-
-### Custom Error Messages
-
-```typescript
-const schema = v.string().min(8, 'Password must be at least 8 characters');
-
-const result = schema.safeParse('short');
-if (!result.success) {
-  console.log(result.error.message); // 'Password must be at least 8 characters'
-}
-```
-
-## Internationalization (i18n)
-
-VLD supports 27+ languages out of the box with comprehensive error messages:
-
-```typescript
-import { v, setLocale } from '@oxog/vld';
-
-// Default is English
-const schema = v.string().min(5);
-schema.safeParse('Hi'); // Error: "String must be at least 5 characters"
-
-// Switch to Turkish
-setLocale('tr');
-schema.safeParse('Hi'); // Error: "Metin en az 5 karakter olmali"
-
-// Switch to Spanish
-setLocale('es');
-schema.safeParse('Hi'); // Error: "La cadena debe tener al menos 5 caracteres"
-
-// Switch to Japanese
-setLocale('ja');
-schema.safeParse('Hi'); // Error: "..."
-```
-
-### Supported Languages
-
-#### Base Languages (15):
-- English (`en`) - Turkish (`tr`) - Spanish (`es`) - French (`fr`) - German (`de`)
-- Italian (`it`) - Portuguese (`pt`) - Russian (`ru`) - Japanese (`ja`) - Korean (`ko`)
-- Chinese (`zh`) - Arabic (`ar`) - Hindi (`hi`) - Dutch (`nl`) - Polish (`pl`)
-
-#### European Languages (4):
-- Danish (`da`) - Swedish (`sv`) - Norwegian (`no`) - Finnish (`fi`)
-
-#### Asian Languages (4):
-- Thai (`th`) - Vietnamese (`vi`) - Indonesian (`id`) - Bengali (`bn`)
-
-#### African Languages (2):
-- Swahili (`sw`) - Afrikaans (`af`)
-
-#### American Languages (2):
-- Portuguese Brazil (`pt-BR`) - Spanish Mexico (`es-MX`)
-
-**Plus 75+ additional languages** supported through comprehensive type definitions with English fallback.
-
-## Error Handling & Formatting
-
-VLD provides advanced error formatting utilities similar to Zod's error handling system.
-
-### Error Formatting Utilities
-
-```typescript
-import { v, VldError, treeifyError, prettifyError, flattenError } from '@oxog/vld';
-
-const userSchema = v.object({
-  username: v.string().min(3),
-  favoriteNumbers: v.array(v.number()),
-  profile: v.object({
-    name: v.string(),
-    email: v.string().email()
-  })
-});
-
-const result = userSchema.safeParse({
-  username: 'ab',
-  favoriteNumbers: [1, 'two', 3],
-  profile: {
-    name: '',
-    email: 'invalid-email'
-  },
-  extraField: 'not allowed'
-});
-
-if (!result.success) {
-  const error = result.error as VldError;
-
-  // 1. Tree Format - Nested structure for complex UIs
-  const tree = treeifyError(error);
-
-  // 2. Pretty Format - Human-readable console output
-  const pretty = prettifyError(error);
-
-  // 3. Flatten Format - Simple form validation
-  const flattened = flattenError(error);
-}
-```
-
-### Using Error Formats in Practice
-
-#### React Form Validation
-```typescript
-function UserForm() {
-  const [errors, setErrors] = useState<VldFlattenedError | null>(null);
-
-  const handleSubmit = (data: unknown) => {
-    const result = userSchema.safeParse(data);
-
-    if (!result.success) {
-      setErrors(flattenError(result.error as VldError));
-    } else {
-      setErrors(null);
-    }
-  };
-
-  return (
-    <form onSubmit={handleSubmit}>
-      {errors?.formErrors.map(error => (
-        <div key={error} className="form-error">{error}</div>
-      ))}
-
-      <input name="username" />
-      {errors?.fieldErrors.username?.map(error => (
-        <div key={error} className="field-error">{error}</div>
-      ))}
-    </form>
-  );
-}
-```
-
-#### API Error Responses
-```typescript
-app.post('/api/users', (req, res) => {
-  const result = userSchema.safeParse(req.body);
-
-  if (!result.success) {
-    const tree = treeifyError(result.error as VldError);
-    res.status(400).json({
-      error: 'Validation failed',
-      details: tree
-    });
-  }
-});
-```
-
-## Advanced Examples
-
-### Complex Validation with New Features
-
-```typescript
-const postSchema = v.object({
-  id: v.union(v.string().uuid(), v.number()),
-  title: v.string().min(5).max(100),
-  content: v.string().min(10),
-  author: v.object({
-    name: v.string(),
-    email: v.string().email(),
-    age: v.coerce.number(),
-  }),
-  tags: v.set(v.string()).default(new Set()),
-  metadata: v.record(v.any()),
-  coordinates: v.tuple(v.number(), v.number()),
-  publishedAt: v.date().default(() => new Date()),
-  status: v.enum('draft', 'published', 'archived')
-});
-
-// Extend with additional fields
-const blogPostSchema = postSchema.extend({
-  viewCount: v.bigint().default(0n),
-  categories: v.array(v.string()).min(1),
-  featured: v.boolean().default(false)
-});
-```
-
-### Discriminated Union
-
-```typescript
-const eventSchema = v.discriminatedUnion('type',
-  v.object({
-    type: v.literal('click'),
-    x: v.number(),
-    y: v.number()
-  }),
-  v.object({
-    type: v.literal('scroll'),
-    direction: v.enum('up', 'down'),
-    distance: v.number()
-  }),
-  v.object({
-    type: v.literal('keypress'),
-    key: v.string(),
-    modifiers: v.array(v.enum('ctrl', 'alt', 'shift'))
-  })
-);
-
-// Type-safe parsing
-const event = eventSchema.parse({
-  type: 'click',
-  x: 100,
-  y: 200
-});
-```
-
-### Recursive Schemas
-
-```typescript
-const categorySchema: ReturnType<typeof v.lazy> = v.lazy(() =>
-  v.object({
-    name: v.string(),
-    slug: v.string().regex(/^[a-z0-9-]+$/),
-    children: v.array(categorySchema).optional()
-  })
-);
-
-const category = categorySchema.parse({
-  name: 'Electronics',
-  slug: 'electronics',
-  children: [
-    {
-      name: 'Phones',
-      slug: 'phones',
-      children: [
-        { name: 'Smartphones', slug: 'smartphones' }
-      ]
-    }
-  ]
-});
-```
-
-### Type-Safe Forms
-
-```typescript
-const loginSchema = v.object({
-  username: v.string().min(3),
-  password: v.string().min(8),
-  rememberMe: v.optional(v.boolean())
-});
-
-type LoginForm = Infer<typeof loginSchema>;
-
-function handleLogin(data: unknown) {
-  const result = loginSchema.safeParse(data);
-
-  if (result.success) {
-    const { username, password, rememberMe } = result.data;
-    // ... handle login
-  }
-}
-```
-
-## Codecs - Bidirectional Transformations
-
-VLD introduces **codecs** - powerful bidirectional transformations that can convert data between different representations.
-
-### What are Codecs?
-
-Codecs enable safe, type-checked conversions between different data formats:
-
-```typescript
-import { stringToNumber, jsonCodec, base64ToBytes } from '@oxog/vld';
-
-// String to number conversion
-const age = stringToNumber.parse('25'); // 25
-const price = stringToNumber.encode(99.99); // "99.99"
-
-// JSON codec
-const userJson = jsonCodec();
-const user = userJson.parse('{"name":"John","age":30}');
-const jsonString = userJson.encode(user);
-
-// Binary data
-const bytes = base64ToBytes.parse('SGVsbG8gV29ybGQ=');
-```
-
-### Built-in Codecs
-
-#### String Conversion Codecs
-```typescript
-import { stringToNumber, stringToInt, stringToBigInt, stringToBoolean } from '@oxog/vld';
-
-stringToNumber.parse('42.5');     // 42.5
-stringToInt.parse('42');          // 42
-stringToBigInt.parse('123n');     // 123n
-stringToBoolean.parse('true');    // true
-```
-
-#### Date Conversion Codecs
-```typescript
-import { isoDatetimeToDate, epochSecondsToDate, epochMillisToDate } from '@oxog/vld';
-
-isoDatetimeToDate.parse('2023-12-25T10:30:00.000Z'); // Date
-epochSecondsToDate.parse(1703505000);                // Date
-epochMillisToDate.parse(1703505000000);              // Date
-```
-
-#### URL Codecs
-```typescript
-import { stringToURL, stringToHttpURL, uriComponent } from '@oxog/vld';
-
-stringToURL.parse('https://example.com/path?q=1');
-stringToHttpURL.parse('https://api.example.com');
-uriComponent.parse('Hello World!'); // "Hello%20World!"
-```
-
-#### Binary Data Codecs
-```typescript
-import { base64ToBytes, hexToBytes, utf8ToBytes, bytesToUtf8 } from '@oxog/vld';
-
-base64ToBytes.parse('SGVsbG8=');           // Uint8Array
-hexToBytes.parse('48656c6c6f');            // Uint8Array
-utf8ToBytes.parse('Hello');                // Uint8Array
-bytesToUtf8.parse(new Uint8Array([72, 101, 108, 108, 111])); // "Hello"
-```
-
-### Custom Codecs
-
-```typescript
-const csvToArray = v.codec(
-  v.string(),
-  v.array(v.string()),
-  {
-    decode: (csv: string) => csv.split(',').map(s => s.trim()),
-    encode: (arr: string[]) => arr.join(', ')
-  }
-);
-
-const tags = csvToArray.parse('react, typescript, vld');
-// ["react", "typescript", "vld"]
-
-const csvString = csvToArray.encode(['node', 'express', 'api']);
-// "node, express, api"
-```
-
-## Plugin System
-
-VLD v1.5.0 introduces a powerful plugin system for extending functionality.
-
-### Creating a Plugin
-
-```typescript
-import { definePlugin, usePlugin, v } from '@oxog/vld';
-
-// Define a custom plugin
-const myPlugin = definePlugin({
-  name: 'my-plugin',
-  version: '1.0.0',
-
-  // Custom validators
-  validators: {
-    phoneNumber: () => v.string().regex(/^\+?[1-9]\d{1,14}$/),
-    postalCode: () => v.string().regex(/^\d{5}(-\d{4})?$/)
-  },
-
-  // Custom transforms
-  transforms: {
-    normalizePhone: (phone: string) => phone.replace(/[^\d+]/g, '')
-  },
-
-  // Lifecycle hooks
-  install(kernel) {
-    console.log('Plugin installed!');
-  }
-});
-
-// Register the plugin
-usePlugin(myPlugin);
-```
-
-### Using Plugin Validators
-
-```typescript
-import { createVldKernel, usePlugin } from '@oxog/vld';
-
-const kernel = createVldKernel({ debug: true });
-
-kernel.use(myPlugin);
-
-// Access custom validators
-const phoneSchema = kernel.validator('phoneNumber');
-phoneSchema.parse('+1234567890');
-```
-
-## Result Pattern
-
-VLD v1.5.0 includes a functional Result pattern for error handling.
-
-### Basic Usage
-
-```typescript
-import { Ok, Err, match, map, flatMap, tryCatch } from '@oxog/vld';
-
-// Create results
-const success = Ok(42);
-const failure = Err(new Error('Something went wrong'));
-
-// Pattern matching
-const message = match(success, {
-  ok: (value) => `Got: ${value}`,
-  err: (error) => `Error: ${error.message}`
-});
-
-// Transform results
-const doubled = map(success, (n) => n * 2); // Ok(84)
-
-// Chain operations
-const result = flatMap(success, (n) =>
-  n > 0 ? Ok(n * 2) : Err(new Error('Must be positive'))
-);
-
-// Safe function execution
-const parsed = tryCatch(() => JSON.parse('{"a":1}'));
-```
-
-### With Validation
-
-```typescript
-import { v, isOk, isErr, unwrapOr } from '@oxog/vld';
-
-const schema = v.object({
-  name: v.string(),
-  age: v.number().min(0)
-});
-
-const result = schema.safeParse(data);
-
-if (isOk(result)) {
-  console.log('Valid:', result.data);
-} else {
-  console.log('Invalid:', result.error);
-}
-
-// With default value
-const user = unwrapOr(result, { name: 'Guest', age: 0 });
-```
-
-### Combining Results
-
-```typescript
-import { all, fromNullable } from '@oxog/vld';
-
-// Combine multiple results
-const results = [Ok(1), Ok(2), Ok(3)];
-const combined = all(results); // Ok([1, 2, 3])
-
-// Convert nullable to Result
-const maybeValue: string | null = getValue();
-const result = fromNullable(maybeValue, new Error('Value is null'));
-```
-
-## CLI Tools
-
-VLD includes command-line tools for validation and benchmarking.
-
-### Installation
-
-```bash
-npm install -g @oxog/vld
-# or use npx
-npx vld --help
-```
-
-### Commands
-
-```bash
-# Show help
-vld --help
-
-# Validate data
-vld validate schema.json data.json
-
-# Run benchmarks
-vld benchmark
-
-# Show version
-vld --version
-```
-
-### Programmatic CLI
-
-```typescript
-import { createCli, vldCli } from '@oxog/vld/cli';
-
-// Use the built-in CLI
-vldCli.run(process.argv.slice(2));
-
-// Or create a custom CLI
-const cli = createCli('my-app', '1.0.0', 'My validation app')
-  .command({
-    name: 'validate',
-    description: 'Validate data',
-    action: async (args, options) => {
-      // Custom validation logic
-    }
-  });
-
-cli.run(process.argv.slice(2));
-```
-
-## Logger & Colored Output
-
-VLD includes a logging system and colored terminal output.
-
-### Logger
-
-```typescript
-import { createLogger, setLogLevel, enableDebug } from '@oxog/vld';
-
-// Create a logger
-const logger = createLogger({ prefix: 'VLD' });
-
-logger.info('Processing...');
-logger.warn('Deprecated feature');
-logger.error('Validation failed');
-logger.debug('Debug info');
-
-// Set log level globally
-setLogLevel('debug');
-
-// Enable debug mode
-enableDebug();
-```
-
-### Colored Output (Pigment)
-
-```typescript
-import { pigment, red, green, blue, bold, dim } from '@oxog/vld';
-
-console.log(red('Error!'));
-console.log(green('Success!'));
-console.log(bold(blue('Important')));
-console.log(dim('Less important'));
-
-// Or use the pigment object
-console.log(pigment.red('Error!'));
-console.log(pigment.bold(pigment.green('Success!')));
-```
-
-## VLD vs. Zod
-
-VLD is designed as a compelling alternative to Zod, offering full feature parity while delivering significant improvements.
-
-### Feature Comparison
-
-| Feature                 | VLD                                | Zod                                  |
-| ----------------------- | ---------------------------------- | ------------------------------------ |
-| **Performance**         | **Release-gated faster runtime, startup, and memory paths** | Baseline                             |
-| **Memory Usage**        | **~4.85x less** overall            | Baseline                             |
-| **Internationalization**| **Built-in (27+ languages)**       | Requires third-party library         |
-| **Dependencies**        | **Zero**                           | `zod-i18n` for locales               |
-| **Bundle Size**         | Smaller                            | Larger                               |
-| **API**                 | 100% Zod-compatible                | Standard Zod API                     |
-| **Plugin System**       | **Built-in**                       | Not available                        |
-| **Result Pattern**      | **Built-in**                       | Not available                        |
-| **CLI Tools**           | **Built-in**                       | Not available                        |
-| **Codecs**              | Built-in, bidirectional            | Built-in                             |
-| **Type Inference**      | Excellent                          | Excellent                            |
-
-### Seamless Migration from Zod
-
-```javascript
-// Before (Zod)
-import { z } from 'zod';
-const schema = z.string().email();
-
-// After (VLD) - Exact same syntax!
-import { v } from '@oxog/vld';
-const schema = v.string().email();
-```
-
-### Drop-in Package Subpaths
-
-VLD also exposes Zod-compatible package subpaths so applications that import Zod 4 entry points can migrate by changing the package name:
-
-```typescript
-// Before
-import { z } from 'zod';
-import * as core from 'zod/v4/core';
-import * as mini from 'zod/v4-mini';
-import * as locales from 'zod/v4/locales';
-
-// After
-import { z } from '@oxog/vld';
-import * as core from '@oxog/vld/v4/core';
-import * as mini from '@oxog/vld/v4-mini';
-import * as locales from '@oxog/vld/v4/locales';
-```
-
-Release checks enforce zero missing exports and zero `typeof` mismatches for `zod/v4`, `zod/v4-mini`, `zod/v4/mini`, `zod/v4/core`, and `zod/v4/locales` against the installed latest Zod.
-
-### Real App Drop-in Verification
-
-`npm run verify:drop-in` creates two temporary TypeScript applications from the same fixture:
-
-- One imports and runs against real `zod`.
-- One imports and runs against the locally built `@oxog/vld` package.
-- The fixture exercises root APIs, `v4`, `v4-mini`, `v4/core`, `v4/locales`, parsing, error formatting, JSON Schema output, mini helpers, and core factories.
-- The normalized runtime outputs must match exactly.
-
-## Benchmarks
-
-### Performance Results
-
-Median of 11 samples per case against Zod 4.4.3, the latest stable release at the time of measurement. The release gate also runs focused runtime, startup, memory, package, install, security, Zod parity, and real drop-in app checks before publishing.
-
-| Test Case | VLD Median Performance | Improvement |
-|-----------|----------------|-------------|
-| Simple String | 719.2M ops/sec | **3.40x faster** |
-| Email Validation | 22.1M ops/sec | **2.87x faster** |
-| Top-level Email Format | 22.8M ops/sec | **3.66x faster** |
-| StringBool Validation | 32.7M ops/sec | **3.44x faster** |
-| Number Validation | 226.2M ops/sec | **27.62x faster** |
-| Simple Object | 37.7M ops/sec | **1.40x faster** |
-| Complex Object | 2.3M ops/sec | **1.02x faster** |
-| Array Validation | 39.8M ops/sec | **6.74x faster** |
-| Union Types | 38.1M ops/sec | **4.10x faster** |
-| Optional Values | 236.9M ops/sec | **7.57x faster** |
-| Nullable Values | 224.7M ops/sec | **10.71x faster** |
-| Nullish Values | 228.4M ops/sec | **52.92x faster** |
-| Default Values | 207.8M ops/sec | **9.71x faster** |
-| Catch Values | 232.1M ops/sec | **46.58x faster** |
-| SafeParse | 162.0M ops/sec | **1.80x faster** |
-| Type Coercion | 204.5M ops/sec | **8.72x faster** |
-| Enum Validation | 180.3M ops/sec | **1.32x faster** |
-| Discriminated Union | 19.2M ops/sec | **1.79x faster** |
-| Tuple Validation | 50.0M ops/sec | **7.99x faster** |
-| Record Validation | 10.7M ops/sec | **5.63x faster** |
-| Set Validation | 18.9M ops/sec | **1.84x faster** |
-| Map Validation | 14.8M ops/sec | **2.37x faster** |
-| BigInt Validation | 164.8M ops/sec | **14.88x faster** |
-| Date Validation | 227.2M ops/sec | **2.57x faster** |
-| Symbol Validation | 230.0M ops/sec | **1.01x faster** |
-| Any Validation | 232.5M ops/sec | **1.01x faster** |
-| Unknown Validation | 234.9M ops/sec | **1.04x faster** |
-| Function Validation | 233.6M ops/sec | **3.52x faster** |
-| Template Literal Validation | 39.3M ops/sec | **1.15x faster** |
-| Promise Async Validation | 6.3M ops/sec | **1.38x faster** |
-
-**VLD won 30/30 snapshot tests. Release checks additionally enforce runtime, startup, memory, Zod subpath parity, and real drop-in app guard thresholds against Zod.**
-
-### Run Benchmarks
-
-```bash
-# Quick performance comparison
-npm run benchmark
-
-# Median-based stable comparison
-npm run benchmark:stable
-
-# Fast CI-friendly performance regression guard
-npm run benchmark:guard
-
-# Full release gate: lint, source and published types, tests, exports, package and install checks, security audit, Zod parity, real drop-in app verification, and performance guards
-npm run release:check
-
-# Memory usage comparison
-npm run benchmark:memory
-
-# Startup time comparison
-npm run benchmark:startup
-
-# Run all benchmarks
-npm run benchmark:all
-```
-
-## Contributing
-
-Contributions are welcome! Please feel free to submit a Pull Request.
-
-## Links
-
-- [Documentation](https://vld.oxog.dev)
-- [NPM Package](https://www.npmjs.com/package/@oxog/vld)
-- [GitHub Repository](https://github.com/ersinkoc/vld)
-
----
-
-Made with Love by [Ersin KOC](https://github.com/ersinkoc)
+# VLD - Fast & Lightweight TypeScript Validation Library
+
+[![NPM Version](https://img.shields.io/npm/v/@oxog/vld.svg)](https://www.npmjs.com/package/@oxog/vld) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/) [![Zero Dependencies](https://img.shields.io/badge/Dependencies-0-green.svg)](package.json) [![Test Coverage](https://img.shields.io/badge/Coverage-100%25-brightgreen.svg)](package.json)
+
+VLD is a blazing-fast, type-safe validation library for TypeScript and JavaScript with **Zod-compatible root and subpath APIs**. Built with performance in mind, it provides a simple and intuitive API while maintaining excellent type inference and 27+ language internationalization support.
+
+## Table of Contents
+
+- [Features](#features)
+- [Performance](#performance)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [API Reference](#api-reference)
+- [Internationalization (i18n)](#internationalization-i18n)
+- [Error Handling & Formatting](#error-handling--formatting)
+- [Advanced Examples](#advanced-examples)
+- [Codecs - Bidirectional Transformations](#codecs---bidirectional-transformations)
+- [Plugin System](#plugin-system)
+- [Result Pattern](#result-pattern)
+- [CLI Tools](#cli-tools)
+- [Logger & Colored Output](#logger--colored-output)
+- [VLD vs. Zod](#vld-vs-zod)
+- [Benchmarks](#benchmarks)
+- [Contributing](#contributing)
+- [Links](#links)
+
+## Features
+
+### Core Features
+- **Blazing Fast**: Optimized for V8 engine with superior performance
+- **Type-Safe**: Full TypeScript support with excellent type inference
+- **Zero Dependencies**: Lightweight with no external dependencies
+- **Tree-Shakeable**: Only import what you need
+- **Composable**: Chain validations for complex schemas
+- **Advanced Error Formatting**: Tree, pretty, and flatten error utilities
+- **Multi-language**: Built-in support for 27+ languages
+- **100% Statement / Branch / Function / Line Coverage**: Rigorously tested with 2502 passing tests
+- **Release-Gated Performance**: CI guards require VLD to stay faster than the latest stable Zod across runtime, startup, and memory benchmarks
+- **Drop-in App Verification**: A real TypeScript fixture is compiled and run once with `zod` and once with built VLD, then normalized runtime output is compared
+- **Audited Compatibility Contract**: Modern Zod 4.4.3 factory signatures, schema direction methods, release-fix behaviors, and JSON Schema defaults are differential-tested; see [the compatibility policy](docs/ZOD_COMPATIBILITY.md)
+
+### Advanced Zod-Compatible Features
+- **Type Coercion**: `v.coerce.string()`, `v.coerce.number()`, `v.coerce.boolean()`, etc.
+- **Advanced Types**: BigInt, Symbol, Tuple, Record, Set, Map validation
+- **Intersection Types**: Combine multiple schemas with intelligent merging
+- **Custom Validation**: `refine()` for custom predicates and validation logic
+- **Data Transformation**: `transform()` for post-validation data transformation
+- **Default Values**: `default()` for handling undefined inputs elegantly
+- **Fallback Handling**: `catch()` for graceful error recovery
+- **Object Utilities**: `pick()`, `omit()`, `extend()` for flexible object schemas
+
+### New in v2.2.x - Error Parity, Canary Parity, and Minified Builds
+
+#### Zod 4-Compatible Error Issues
+Validation failures now carry Zod 4's structured issue shape, so error-handling code ports across unchanged:
+- `invalid_type` issues expose `expected` and `received` and use the `"Invalid input: expected X, received Y"` message format
+- `too_small` / `too_big` issues expose `minimum`, `maximum`, `origin`, and `inclusive`
+- `invalid_format` issues expose `format`, `origin`, and `pattern`; `invalid_value` issues expose a `values` array
+- `parse()` throws `VldError` (which extends `Error`) for every validator, matching Zod's throw behavior
+
+#### New Parity Helpers
+```typescript
+import { v, deepPartial, input, output } from '@oxog/vld';
+
+v.creditCard().parse('4242424242424242');   // regex plus Luhn checksum
+
+const schema = v.object({
+  profile: v.object({ name: v.string(), age: v.number() })
+});
+
+const draft = deepPartial(schema);      // every nested field optional
+const inputSide = input(schema);        // input-side view of a pipe
+const outputSide = output(schema);      // output-side view of a pipe
+```
+- `deepPartial()` walks children first, mirroring Zod's `visit.js` ordering, and stays cycle-safe through lazy deferral
+- `input()` / `output()` resolve pipe direction the way Zod's root helpers do
+- `@oxog/vld/v4/core` gained the matching `_creditCard`, `isValidCreditCard`, `standardProps`, `handleUnrepresentable`, `$ZodCyclicError`, `attachMemoizer`, and `isBackEdge` shims
+
+#### Minified Release Builds
+- Release artifacts ship minified by default (opt out with `VLD_MINIFY=0`)
+- Mangling preserves `/^Vld/` class names, because JSON Schema conversion dispatches on `schema.constructor.name`
+- A built-CJS guard in `verify:drop-in` asserts name-dispatched composites against the minified bundle, so this can never silently regress again
+
+### NEW in v2.0.0 - Modular Architecture
+
+#### Tree-Shakable Mini API
+```typescript
+import { string, number, object, optional } from '@oxog/vld/mini';
+
+const schema = object({
+  name: string().min(1),
+  age: optional(number().positive()),
+});
+```
+- **82% smaller bundles** when using only needed validators
+- Individual factory functions for optimal tree-shaking
+- Full TypeScript support with identical type inference
+
+#### Lazy Locale Loading
+
+> **Bundle-size contract:** the lazy entrypoint is published as
+> `@oxog/vld/locales/lazy` (`src/locales/lazy.ts`). It uses dynamic `import()`
+> for each locale on first use, so tree-shaken bundles ship **only English by
+> default**. Importing the plain `@oxog/vld/locales` subpath (or the root
+> `@oxog/vld` package) eagerly pulls every locale into the graph; pick the
+> `lazy` subpath if you only need one or two languages in production.
+
+```typescript
+import { setLocaleAsync, preloadLocales } from '@oxog/vld/locales/lazy';
+
+// First call loads the locale on demand; subsequent calls hit the cache.
+await setLocaleAsync('tr');
+
+// SSR / batch warm-up: preload what you need before serving traffic.
+await preloadLocales(['en', 'de', 'ja']);
+```
+- **92% bundle reduction** when you only ship English plus the locales you pre-load
+- `setLocaleAsync()` is true async dynamic-import, not a sync wrapper
+- `preloadLocales()` for SSR/batch loading
+- Backwards-compatible `setLocale()` is still available on the eager entrypoint
+
+#### Dual ESM/CJS Build
+- ESM builds for modern bundlers (Vite, esbuild)
+- CJS builds for Node.js and legacy environments
+- Proper `exports` field with conditional exports
+
+### NEW in v1.5.0 - Major Platform Release
+
+#### Plugin System
+- **`definePlugin()`**: Create custom plugins with validators, transforms, and codecs
+- **`usePlugin()`**: Register plugins globally
+- **Plugin Hooks**: Lifecycle hooks for validation events
+- **Custom Validators**: Extend VLD with your own validators
+
+#### Result Pattern
+- **`Ok()`/`Err()`**: Functional error handling
+- **`match()`**: Pattern matching on results
+- **`map()`/`flatMap()`**: Transform results
+- **`tryCatch()`**: Safe function execution
+- **`all()`**: Combine multiple results
+
+#### Event System
+- **`createEmitter()`**: Type-safe event emitter
+- **`createEventBus()`**: Global event bus
+- **Validation Events**: Parse start, success, error, field validation
+
+#### CLI Tools
+- **`vld validate`**: Validate data from command line
+- **`vld benchmark`**: Run performance benchmarks
+- **Colored Output**: Beautiful terminal output with pigment
+
+#### New Validators
+- **`v.discriminatedUnion()`**: Discriminated union types
+- **`v.xor()`**: Exclusive OR validation
+- **`v.file()`**: File upload validation
+- **`v.function()`**: Function validation
+- **`v.custom()`**: Type-safe custom validators
+- **`v.json()`**: JSON string validation with schema
+- **`v.lazy()`**: Recursive schema support
+- **`v.nan()`**: NaN validation
+- **`v.null()`**: Null validation
+- **`v.undefined()`**: Undefined validation
+- **`v.templateLiteral()`**: Template literal types
+
+#### New String Format Validators
+- **`v.hostname()`**: Hostname validation
+- **`v.emoji()`**: Emoji validation
+- **`v.base64()`/`v.base64url()`**: Base64 format validation
+- **`v.hex()`**: Hex string validation
+- **`v.jwt()`**: JWT format validation
+- **`v.nanoid()`/`v.cuid()`/`v.cuid2()`/`v.ulid()`**: ID format validation
+- **`v.mac()`**: MAC address validation
+- **`v.cidrv4()`/`v.cidrv6()`**: CIDR block validation
+- **`v.e164()`**: E.164 phone number validation
+- **`v.hash()`**: Hash validation (md5, sha1, sha256, sha384, sha512)
+- **`v.iso.date()`/`v.iso.time()`/`v.iso.dateTime()`/`v.iso.duration()`**: ISO format validation
+
+#### Enhanced Object Utilities
+- **`v.strictObject()`**: Strict mode object validation
+- **`v.looseObject()`**: Passthrough object validation
+- **`v.partialRecord()`**: Partial record validation
+- **`v.looseRecord()`**: Loose record validation
+- **`v.int()`**: Integer shortcut
+- **`v.int32()`**: 32-bit integer shortcut
+- **`v.nullish()`**: Null or undefined
+- **`v.NEVER`**: NEVER constant for transforms (Zod 4 parity)
+
+### Codec System - Beyond Zod
+- **Bidirectional Transformations**: Full encode/decode support for data conversion
+- **19 Built-in Codecs**: String conversions, date parsing, JSON, URL, binary data
+- **Zod-Compatible**: All `stringToNumber`, `jsonCodec`, `base64ToBytes`, etc.
+- **Async Support**: Both sync and async codec operations
+- **Custom Codecs**: Create your own bidirectional transformations
+- **Type-Safe**: Full TypeScript support with perfect type inference
+
+## Performance
+
+VLD is designed for speed and efficiency with recent optimizations delivering exceptional performance:
+
+### Release-Gated Speed Benchmarks (v2.2.1 vs Zod 4.4.3)
+- Runtime guard: VLD must stay at least 1.2x faster on every guarded hot path and keep at least a 3x average ratio
+- Startup guard: cross-platform floors are 0.85x import, 0.9x total startup, and 1.25x warm parse versus Zod
+- Memory guard: VLD must keep at least 2x lower total retained heap, 1.5x higher aggregate throughput, and no guarded case below 1.1x speed
+
+### Latest Runtime Guard Snapshot
+
+Measured with `npm run benchmark:guard` (5 samples per case) against Zod 4.4.3:
+
+| Guarded case | VLD | Zod | Ratio |
+|--------------|-----|-----|-------|
+| Nullish parse | 214.1M ops/sec | 7.0M ops/sec | **30.70x** |
+| Number positive int parse | 252.9M ops/sec | 27.8M ops/sec | **9.10x** |
+| Discriminated union parse | 35.0M ops/sec | 8.6M ops/sec | **4.06x** |
+| Optional parse | 212.9M ops/sec | 56.6M ops/sec | **3.76x** |
+| Union string and number parse | 39.1M ops/sec | 11.9M ops/sec | **3.30x** |
+| Simple string parse | 620.7M ops/sec | 208.8M ops/sec | **2.97x** |
+| Array number parse | 49.2M ops/sec | 28.3M ops/sec | **1.74x** |
+| Simple object parse | 45.2M ops/sec | 27.7M ops/sec | **1.63x** |
+
+8/8 guarded cases pass with a **7.16x average ratio**. Absolute ops/sec numbers are hardware-dependent; the ratios are what the release gate enforces.
+
+### Optimizations
+- **110x improvement** in union type validation
+- **Simplified email regex** for maximum performance
+- **Inline type checks** in object validation
+- **Optimized loops** with direct array assignment
+- **SafeParse optimization** to avoid try-catch overhead
+- **Pre-computed keys** with Set for O(1) lookups
+
+### Memory Efficiency
+
+Measured with `npm run benchmark:memory` against Zod 4.4.3. Heap deltas move a few percent between runs, so treat these as approximate:
+
+- **~12.7x less memory** for schema creation
+- **~7.3x less memory** for union validation
+- **~2.9x less memory** for simple string validation
+- **~2.7x less memory** for complex object validation
+- **~5x less memory** overall
+
+### A Note on Real-World Benchmarking
+
+Many validation library benchmarks can be misleading because they often test with **reused schema instances**:
+
+```javascript
+// What benchmarks typically test (unrealistic):
+const schema = z.string();
+for (let i = 0; i < 1000000; i++) {
+  schema.parse(data); // Same instance reused
+}
+
+// What happens in real applications:
+app.post('/api/user', (req, res) => {
+  // New schema created for each request
+  const schema = z.object({
+    email: z.string().email(),
+    age: z.number().min(18)
+  });
+  schema.parse(req.body);
+});
+```
+
+When testing real-world patterns:
+- **Creating new instances**: VLD is **2000x faster** than Zod
+- **Reused instances**: Zod benefits from V8's singleton optimization
+- **Real applications**: Schemas are often created dynamically, where VLD excels
+
+Run `npm run benchmark:truth` to see the real performance difference.
+
+## Installation
+
+```bash
+npm install @oxog/vld
+# or
+yarn add @oxog/vld
+# or
+pnpm add @oxog/vld
+```
+
+## Quick Start
+
+```typescript
+import { v } from '@oxog/vld';
+
+// It is recommended to import as `v` for consistency with Zod's `z`
+// and for a more concise syntax.
+
+// Define a schema
+const userSchema = v.object({
+  name: v.string().min(2),
+  email: v.string().email(),
+  age: v.number().min(18).max(100),
+  isActive: v.boolean()
+});
+
+// Validate data
+const result = userSchema.safeParse({
+  name: 'John Doe',
+  email: 'john@example.com',
+  age: 25,
+  isActive: true
+});
+
+if (result.success) {
+  console.log('Valid user:', result.data);
+} else {
+  console.log('Validation error:', result.error);
+}
+```
+
+For advanced error formatting:
+```typescript
+import { v, VldError, treeifyError, prettifyError, flattenError } from '@oxog/vld';
+```
+
+## API Reference
+
+### Basic Types
+
+```typescript
+v.string()    // String validation
+v.number()    // Number validation
+v.int()       // Integer validation (shortcut)
+v.int32()     // 32-bit integer validation
+v.boolean()   // Boolean validation
+v.bigint()    // BigInt validation
+v.symbol()    // Symbol validation
+v.date()      // Date validation
+v.uint8array()// Uint8Array validation
+v.literal()   // Literal values
+v.enum()      // Enum values (supports TypeScript enums)
+v.any()       // Any type
+v.unknown()   // Unknown type
+v.void()      // Void type
+v.never()     // Never type
+v.null()      // Null type
+v.undefined() // Undefined type
+v.nan()       // NaN type
+```
+
+### Advanced Types
+
+```typescript
+// Collections
+v.array(v.string())                    // Array validation
+v.tuple(v.string(), v.number())        // Fixed-length tuple
+v.record(v.number())                   // Record/dictionary validation
+v.set(v.string())                      // Set validation
+v.map(v.string(), v.number())          // Map validation
+
+// Objects
+v.object({                             // Object schema
+  name: v.string(),
+  age: v.number()
+})
+v.strictObject({...})                  // No extra fields allowed
+v.looseObject({...})                   // Extra fields passed through
+
+// Composition
+v.union(v.string(), v.number())        // Union types
+v.intersection(schemaA, schemaB)       // Intersection types
+v.discriminatedUnion('type', ...)      // Discriminated union
+v.xor(schemaA, schemaB)               // Exclusive OR
+v.optional(v.string())                 // Optional fields
+v.nullable(v.string())                 // Nullable fields
+v.nullish(v.string())                  // Null or undefined
+```
+
+### String Validators
+
+```typescript
+v.string()
+  .min(5)                    // Minimum length
+  .max(10)                   // Maximum length
+  .length(8)                 // Exact length
+  .email()                   // Email format
+  .url()                     // URL format
+  .uuid()                    // UUID format
+  .regex(/pattern/)          // Custom regex
+  .startsWith('prefix')      // String prefix
+  .endsWith('suffix')        // String suffix
+  .includes('substring')     // Contains substring
+  .ip()                      // IP address (v4 or v6)
+  .trim()                    // Trim whitespace
+  .toLowerCase()             // Convert to lowercase
+  .toUpperCase()             // Convert to uppercase
+  .nonempty()               // Non-empty string
+```
+
+### String Format Validators (Top-Level)
+
+```typescript
+v.email()                    // Email validation
+v.uuid()                     // UUID validation
+v.uuid({ version: 'v4' })    // UUID v4 validation
+v.uuidv4()                   // UUID v4 shortcut
+v.hostname()                 // Hostname validation
+v.emoji()                    // Emoji validation
+v.base64()                   // Base64 format
+v.base64url()                // Base64 URL-safe format
+v.hex()                      // Hex string
+v.jwt()                      // JWT format
+v.nanoid()                   // NanoID format
+v.cuid()                     // CUID format
+v.cuid2()                    // CUID2 format
+v.ulid()                     // ULID format
+v.ipv4()                     // IPv4 address
+v.ipv6()                     // IPv6 address
+v.mac()                      // MAC address
+v.cidrv4()                   // IPv4 CIDR block
+v.cidrv6()                   // IPv6 CIDR block
+v.e164()                     // E.164 phone number
+v.creditCard()               // Credit card number (regex plus Luhn checksum)
+v.hash('sha256')             // Hash validation
+v.iso.date()                 // ISO date format
+v.iso.time()                 // ISO time format
+v.iso.dateTime()             // ISO datetime format
+v.iso.duration()             // ISO duration format
+```
+
+### Number Validators
+
+```typescript
+v.number()
+  .min(0)                    // Minimum value
+  .max(100)                  // Maximum value
+  .int()                     // Integer only
+  .positive()                // Positive numbers
+  .negative()                // Negative numbers
+  .nonnegative()            // >= 0
+  .nonpositive()            // <= 0
+  .finite()                  // Finite numbers
+  .safe()                    // Safe integers
+  .multipleOf(5)            // Multiple of value
+```
+
+### Arrays and Objects
+
+```typescript
+// Arrays
+v.array(v.string())          // Array of strings
+  .min(1)                    // Minimum length
+  .max(10)                   // Maximum length
+  .length(5)                 // Exact length
+  .nonempty()               // Non-empty array
+
+// Objects
+v.object({
+  name: v.string(),
+  age: v.number()
+})
+  .partial()                 // All fields optional
+  .strict()                  // No extra fields
+  .passthrough()             // Allow extra fields
+```
+
+### Composite Types
+
+```typescript
+// Optional
+v.optional(v.string())       // string | undefined
+
+// Nullable
+v.nullable(v.string())       // string | null
+
+// Nullish
+v.nullish(v.string())        // string | null | undefined
+
+// Union
+v.union(v.string(), v.number()) // string | number
+
+// Discriminated Union
+v.discriminatedUnion('type',
+  v.object({ type: v.literal('a'), a: v.string() }),
+  v.object({ type: v.literal('b'), b: v.number() })
+)
+
+// Literal
+v.literal('active')          // 'active'
+
+// Enum
+v.enum('red', 'green', 'blue') // 'red' | 'green' | 'blue'
+```
+
+### Type Coercion
+
+```typescript
+// Coerce strings from various types
+v.coerce.string().parse(123)        // "123"
+v.coerce.string().parse(true)       // "true"
+
+// Coerce numbers from strings/booleans
+v.coerce.number().parse("123")      // 123
+v.coerce.number().parse(true)       // 1
+
+// Coerce booleans from strings/numbers
+v.coerce.boolean().parse("true")    // true
+v.coerce.boolean().parse(1)         // true
+
+// Coerce BigInt from strings/numbers
+v.coerce.bigint().parse("123")      // 123n
+v.coerce.bigint().parse(456)        // 456n
+
+// Coerce Date from strings/timestamps
+v.coerce.date().parse("2023-01-01") // Date object
+v.coerce.date().parse(1672531200000) // Date object
+```
+
+### Object Schema Methods
+
+```typescript
+const userSchema = v.object({
+  name: v.string(),
+  age: v.number(),
+  email: v.string(),
+  role: v.string()
+});
+
+// Pick specific fields
+const publicSchema = userSchema.pick('name', 'age');
+// Type: { name: string; age: number }
+
+// Omit sensitive fields
+const safeSchema = userSchema.omit('email', 'role');
+// Type: { name: string; age: number }
+
+// Extend with new fields
+const extendedSchema = userSchema.extend({
+  isActive: v.boolean(),
+  lastLogin: v.date()
+});
+// Type: { name: string; age: number; email: string; role: string; isActive: boolean; lastLogin: Date }
+```
+
+### Advanced Validation Methods
+
+```typescript
+// Custom validation with refine()
+const positiveNumber = v.number()
+  .refine(n => n > 0, "Number must be positive");
+
+// Data transformation with transform()
+const uppercaseString = v.string()
+  .transform(s => s.toUpperCase());
+
+// Default values for undefined
+const withDefault = v.string().default("fallback");
+withDefault.parse(undefined); // "fallback"
+
+// Catch errors and provide fallback
+const withCatch = v.number().catch(-1);
+withCatch.parse("invalid"); // -1
+
+// Method chaining
+const complexSchema = v.string()
+  .min(3)
+  .transform(s => s.trim())
+  .refine(s => s.includes('@'), 'Must contain @')
+  .default('user@example.com');
+```
+
+### Special Validators
+
+```typescript
+// JSON validator with optional schema
+v.json()                           // Any valid JSON
+v.json(v.object({ name: v.string() }))  // Typed JSON
+
+// Lazy for recursive schemas
+const categorySchema = v.lazy(() =>
+  v.object({
+    name: v.string(),
+    children: v.array(categorySchema).optional()
+  })
+);
+
+// Custom validator
+v.custom({
+  check: (val) => typeof val === 'string' && val.length > 0,
+  message: 'Must be a non-empty string'
+});
+
+// File validator
+v.file()
+  .maxSize(5 * 1024 * 1024)  // 5MB
+  .type(['image/png', 'image/jpeg']);
+
+// Function validator
+v.function()
+  .args(v.string(), v.number())
+  .returns(v.boolean());
+```
+
+### Type Inference
+
+```typescript
+import { v } from '@oxog/vld';
+import type { Infer } from '@oxog/vld';
+
+const schema = v.object({
+  name: v.string(),
+  age: v.number()
+});
+
+// Automatically infer the type
+type User = Infer<typeof schema>;
+// { name: string; age: number }
+```
+
+### Error Formatting Types
+
+```typescript
+import { VldError } from '@oxog/vld';
+import type {
+  VldIssue,           // Individual validation issue
+  VldErrorTree,       // Nested error structure
+  VldFlattenedError   // Flattened error structure
+} from '@oxog/vld';
+```
+
+### Custom Error Messages
+
+```typescript
+const schema = v.string().min(8, 'Password must be at least 8 characters');
+
+const result = schema.safeParse('short');
+if (!result.success) {
+  console.log(result.error.message); // 'Password must be at least 8 characters'
+}
+```
+
+## Internationalization (i18n)
+
+VLD supports 27+ languages out of the box with comprehensive error messages:
+
+```typescript
+import { v, setLocale } from '@oxog/vld';
+
+// Default is English
+const schema = v.string().min(5);
+schema.safeParse('Hi'); // Error: "String must be at least 5 characters"
+
+// Switch to Turkish
+setLocale('tr');
+schema.safeParse('Hi'); // Error: "Metin en az 5 karakter olmali"
+
+// Switch to Spanish
+setLocale('es');
+schema.safeParse('Hi'); // Error: "La cadena debe tener al menos 5 caracteres"
+
+// Switch to Japanese
+setLocale('ja');
+schema.safeParse('Hi'); // Error: "..."
+```
+
+### Supported Languages
+
+#### Base Languages (15):
+- English (`en`) - Turkish (`tr`) - Spanish (`es`) - French (`fr`) - German (`de`)
+- Italian (`it`) - Portuguese (`pt`) - Russian (`ru`) - Japanese (`ja`) - Korean (`ko`)
+- Chinese (`zh`) - Arabic (`ar`) - Hindi (`hi`) - Dutch (`nl`) - Polish (`pl`)
+
+#### European Languages (4):
+- Danish (`da`) - Swedish (`sv`) - Norwegian (`no`) - Finnish (`fi`)
+
+#### Asian Languages (4):
+- Thai (`th`) - Vietnamese (`vi`) - Indonesian (`id`) - Bengali (`bn`)
+
+#### African Languages (2):
+- Swahili (`sw`) - Afrikaans (`af`)
+
+#### American Languages (2):
+- Portuguese Brazil (`pt-BR`) - Spanish Mexico (`es-MX`)
+
+**Plus 75+ additional languages** supported through comprehensive type definitions with English fallback.
+
+## Error Handling & Formatting
+
+VLD provides advanced error formatting utilities similar to Zod's error handling system.
+
+### Error Formatting Utilities
+
+```typescript
+import { v, VldError, treeifyError, prettifyError, flattenError } from '@oxog/vld';
+
+const userSchema = v.object({
+  username: v.string().min(3),
+  favoriteNumbers: v.array(v.number()),
+  profile: v.object({
+    name: v.string(),
+    email: v.string().email()
+  })
+});
+
+const result = userSchema.safeParse({
+  username: 'ab',
+  favoriteNumbers: [1, 'two', 3],
+  profile: {
+    name: '',
+    email: 'invalid-email'
+  },
+  extraField: 'not allowed'
+});
+
+if (!result.success) {
+  const error = result.error as VldError;
+
+  // 1. Tree Format - Nested structure for complex UIs
+  const tree = treeifyError(error);
+
+  // 2. Pretty Format - Human-readable console output
+  const pretty = prettifyError(error);
+
+  // 3. Flatten Format - Simple form validation
+  const flattened = flattenError(error);
+}
+```
+
+### Using Error Formats in Practice
+
+#### React Form Validation
+```typescript
+function UserForm() {
+  const [errors, setErrors] = useState<VldFlattenedError | null>(null);
+
+  const handleSubmit = (data: unknown) => {
+    const result = userSchema.safeParse(data);
+
+    if (!result.success) {
+      setErrors(flattenError(result.error as VldError));
+    } else {
+      setErrors(null);
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      {errors?.formErrors.map(error => (
+        <div key={error} className="form-error">{error}</div>
+      ))}
+
+      <input name="username" />
+      {errors?.fieldErrors.username?.map(error => (
+        <div key={error} className="field-error">{error}</div>
+      ))}
+    </form>
+  );
+}
+```
+
+#### API Error Responses
+```typescript
+app.post('/api/users', (req, res) => {
+  const result = userSchema.safeParse(req.body);
+
+  if (!result.success) {
+    const tree = treeifyError(result.error as VldError);
+    res.status(400).json({
+      error: 'Validation failed',
+      details: tree
+    });
+  }
+});
+```
+
+## Advanced Examples
+
+### Complex Validation with New Features
+
+```typescript
+const postSchema = v.object({
+  id: v.union(v.string().uuid(), v.number()),
+  title: v.string().min(5).max(100),
+  content: v.string().min(10),
+  author: v.object({
+    name: v.string(),
+    email: v.string().email(),
+    age: v.coerce.number(),
+  }),
+  tags: v.set(v.string()).default(new Set()),
+  metadata: v.record(v.any()),
+  coordinates: v.tuple(v.number(), v.number()),
+  publishedAt: v.date().default(() => new Date()),
+  status: v.enum('draft', 'published', 'archived')
+});
+
+// Extend with additional fields
+const blogPostSchema = postSchema.extend({
+  viewCount: v.bigint().default(0n),
+  categories: v.array(v.string()).min(1),
+  featured: v.boolean().default(false)
+});
+```
+
+### Discriminated Union
+
+```typescript
+const eventSchema = v.discriminatedUnion('type',
+  v.object({
+    type: v.literal('click'),
+    x: v.number(),
+    y: v.number()
+  }),
+  v.object({
+    type: v.literal('scroll'),
+    direction: v.enum('up', 'down'),
+    distance: v.number()
+  }),
+  v.object({
+    type: v.literal('keypress'),
+    key: v.string(),
+    modifiers: v.array(v.enum('ctrl', 'alt', 'shift'))
+  })
+);
+
+// Type-safe parsing
+const event = eventSchema.parse({
+  type: 'click',
+  x: 100,
+  y: 200
+});
+```
+
+### Recursive Schemas
+
+```typescript
+const categorySchema: ReturnType<typeof v.lazy> = v.lazy(() =>
+  v.object({
+    name: v.string(),
+    slug: v.string().regex(/^[a-z0-9-]+$/),
+    children: v.array(categorySchema).optional()
+  })
+);
+
+const category = categorySchema.parse({
+  name: 'Electronics',
+  slug: 'electronics',
+  children: [
+    {
+      name: 'Phones',
+      slug: 'phones',
+      children: [
+        { name: 'Smartphones', slug: 'smartphones' }
+      ]
+    }
+  ]
+});
+```
+
+### Type-Safe Forms
+
+```typescript
+const loginSchema = v.object({
+  username: v.string().min(3),
+  password: v.string().min(8),
+  rememberMe: v.optional(v.boolean())
+});
+
+type LoginForm = Infer<typeof loginSchema>;
+
+function handleLogin(data: unknown) {
+  const result = loginSchema.safeParse(data);
+
+  if (result.success) {
+    const { username, password, rememberMe } = result.data;
+    // ... handle login
+  }
+}
+```
+
+## Codecs - Bidirectional Transformations
+
+VLD introduces **codecs** - powerful bidirectional transformations that can convert data between different representations.
+
+### What are Codecs?
+
+Codecs enable safe, type-checked conversions between different data formats:
+
+```typescript
+import { stringToNumber, jsonCodec, base64ToBytes } from '@oxog/vld';
+
+// String to number conversion
+const age = stringToNumber.parse('25'); // 25
+const price = stringToNumber.encode(99.99); // "99.99"
+
+// JSON codec
+const userJson = jsonCodec();
+const user = userJson.parse('{"name":"John","age":30}');
+const jsonString = userJson.encode(user);
+
+// Binary data
+const bytes = base64ToBytes.parse('SGVsbG8gV29ybGQ=');
+```
+
+### Built-in Codecs
+
+#### String Conversion Codecs
+```typescript
+import { stringToNumber, stringToInt, stringToBigInt, stringToBoolean } from '@oxog/vld';
+
+stringToNumber.parse('42.5');     // 42.5
+stringToInt.parse('42');          // 42
+stringToBigInt.parse('123n');     // 123n
+stringToBoolean.parse('true');    // true
+```
+
+#### Date Conversion Codecs
+```typescript
+import { isoDatetimeToDate, epochSecondsToDate, epochMillisToDate } from '@oxog/vld';
+
+isoDatetimeToDate.parse('2023-12-25T10:30:00.000Z'); // Date
+epochSecondsToDate.parse(1703505000);                // Date
+epochMillisToDate.parse(1703505000000);              // Date
+```
+
+#### URL Codecs
+```typescript
+import { stringToURL, stringToHttpURL, uriComponent } from '@oxog/vld';
+
+stringToURL.parse('https://example.com/path?q=1');
+stringToHttpURL.parse('https://api.example.com');
+uriComponent.parse('Hello World!'); // "Hello%20World!"
+```
+
+#### Binary Data Codecs
+```typescript
+import { base64ToBytes, hexToBytes, utf8ToBytes, bytesToUtf8 } from '@oxog/vld';
+
+base64ToBytes.parse('SGVsbG8=');           // Uint8Array
+hexToBytes.parse('48656c6c6f');            // Uint8Array
+utf8ToBytes.parse('Hello');                // Uint8Array
+bytesToUtf8.parse(new Uint8Array([72, 101, 108, 108, 111])); // "Hello"
+```
+
+### Custom Codecs
+
+```typescript
+const csvToArray = v.codec(
+  v.string(),
+  v.array(v.string()),
+  {
+    decode: (csv: string) => csv.split(',').map(s => s.trim()),
+    encode: (arr: string[]) => arr.join(', ')
+  }
+);
+
+const tags = csvToArray.parse('react, typescript, vld');
+// ["react", "typescript", "vld"]
+
+const csvString = csvToArray.encode(['node', 'express', 'api']);
+// "node, express, api"
+```
+
+## Plugin System
+
+VLD v1.5.0 introduces a powerful plugin system for extending functionality.
+
+### Creating a Plugin
+
+```typescript
+import { definePlugin, usePlugin, v } from '@oxog/vld';
+
+// Define a custom plugin
+const myPlugin = definePlugin({
+  name: 'my-plugin',
+  version: '1.0.0',
+
+  // Custom validators
+  validators: {
+    phoneNumber: () => v.string().regex(/^\+?[1-9]\d{1,14}$/),
+    postalCode: () => v.string().regex(/^\d{5}(-\d{4})?$/)
+  },
+
+  // Custom transforms
+  transforms: {
+    normalizePhone: (phone: string) => phone.replace(/[^\d+]/g, '')
+  },
+
+  // Lifecycle hooks
+  install(kernel) {
+    console.log('Plugin installed!');
+  }
+});
+
+// Register the plugin
+usePlugin(myPlugin);
+```
+
+### Using Plugin Validators
+
+```typescript
+import { createVldKernel, usePlugin } from '@oxog/vld';
+
+const kernel = createVldKernel({ debug: true });
+
+kernel.use(myPlugin);
+
+// Access custom validators
+const phoneSchema = kernel.validator('phoneNumber');
+phoneSchema.parse('+1234567890');
+```
+
+## Result Pattern
+
+VLD v1.5.0 includes a functional Result pattern for error handling.
+
+### Basic Usage
+
+```typescript
+import { Ok, Err, match, map, flatMap, tryCatch } from '@oxog/vld';
+
+// Create results
+const success = Ok(42);
+const failure = Err(new Error('Something went wrong'));
+
+// Pattern matching
+const message = match(success, {
+  ok: (value) => `Got: ${value}`,
+  err: (error) => `Error: ${error.message}`
+});
+
+// Transform results
+const doubled = map(success, (n) => n * 2); // Ok(84)
+
+// Chain operations
+const result = flatMap(success, (n) =>
+  n > 0 ? Ok(n * 2) : Err(new Error('Must be positive'))
+);
+
+// Safe function execution
+const parsed = tryCatch(() => JSON.parse('{"a":1}'));
+```
+
+### With Validation
+
+```typescript
+import { v, isOk, isErr, unwrapOr } from '@oxog/vld';
+
+const schema = v.object({
+  name: v.string(),
+  age: v.number().min(0)
+});
+
+const result = schema.safeParse(data);
+
+if (isOk(result)) {
+  console.log('Valid:', result.data);
+} else {
+  console.log('Invalid:', result.error);
+}
+
+// With default value
+const user = unwrapOr(result, { name: 'Guest', age: 0 });
+```
+
+### Combining Results
+
+```typescript
+import { all, fromNullable } from '@oxog/vld';
+
+// Combine multiple results
+const results = [Ok(1), Ok(2), Ok(3)];
+const combined = all(results); // Ok([1, 2, 3])
+
+// Convert nullable to Result
+const maybeValue: string | null = getValue();
+const result = fromNullable(maybeValue, new Error('Value is null'));
+```
+
+## CLI Tools
+
+VLD includes command-line tools for validation and benchmarking.
+
+### Installation
+
+```bash
+npm install -g @oxog/vld
+# or use npx
+npx vld --help
+```
+
+### Commands
+
+```bash
+# Show help
+vld --help
+
+# Validate data
+vld validate schema.json data.json
+
+# Run benchmarks
+vld benchmark
+
+# Show version
+vld --version
+```
+
+### Programmatic CLI
+
+```typescript
+import { createCli, vldCli } from '@oxog/vld/cli';
+
+// Use the built-in CLI
+vldCli.run(process.argv.slice(2));
+
+// Or create a custom CLI
+const cli = createCli('my-app', '1.0.0', 'My validation app')
+  .command({
+    name: 'validate',
+    description: 'Validate data',
+    action: async (args, options) => {
+      // Custom validation logic
+    }
+  });
+
+cli.run(process.argv.slice(2));
+```
+
+## Logger & Colored Output
+
+VLD includes a logging system and colored terminal output.
+
+### Logger
+
+```typescript
+import { createLogger, setLogLevel, enableDebug } from '@oxog/vld';
+
+// Create a logger
+const logger = createLogger({ prefix: 'VLD' });
+
+logger.info('Processing...');
+logger.warn('Deprecated feature');
+logger.error('Validation failed');
+logger.debug('Debug info');
+
+// Set log level globally
+setLogLevel('debug');
+
+// Enable debug mode
+enableDebug();
+```
+
+### Colored Output (Pigment)
+
+```typescript
+import { pigment, red, green, blue, bold, dim } from '@oxog/vld';
+
+console.log(red('Error!'));
+console.log(green('Success!'));
+console.log(bold(blue('Important')));
+console.log(dim('Less important'));
+
+// Or use the pigment object
+console.log(pigment.red('Error!'));
+console.log(pigment.bold(pigment.green('Success!')));
+```
+
+## VLD vs. Zod
+
+VLD is designed as a compelling alternative to Zod, maintaining an audited compatibility baseline while delivering additional platform features.
+
+### Feature Comparison
+
+| Feature                 | VLD                                | Zod                                  |
+| ----------------------- | ---------------------------------- | ------------------------------------ |
+| **Performance**         | **Release-gated faster runtime, startup, and memory paths** | Baseline                             |
+| **Memory Usage**        | **~5x less** overall               | Baseline                             |
+| **Internationalization**| **Built-in 27+ locales with lazy loading** | Built-in locales              |
+| **Dependencies**        | **Zero runtime dependencies**      | Zero runtime dependencies            |
+| **Bundle Size**         | Smaller                            | Larger                               |
+| **API**                 | Zod 4.4.3 compatibility gate + extensions | Standard Zod API                     |
+| **Plugin System**       | **Built-in**                       | Not available                        |
+| **Result Pattern**      | **Built-in**                       | Not available                        |
+| **CLI Tools**           | **Built-in**                       | Not available                        |
+| **Codecs**              | Built-in system plus reusable presets | Built-in primitives; recipes documented |
+| **Type Inference**      | Excellent                          | Excellent                            |
+
+### Seamless Migration from Zod
+
+```javascript
+// Before (Zod)
+import { z } from 'zod';
+const schema = z.string().email();
+
+// After (VLD) - Exact same syntax!
+import { v } from '@oxog/vld';
+const schema = v.string().email();
+```
+
+### Drop-in Package Subpaths
+
+VLD also exposes Zod-compatible package subpaths so applications that import Zod 4 entry points can migrate by changing the package name:
+
+```typescript
+// Before
+import { z } from 'zod';
+import * as core from 'zod/v4/core';
+import * as mini from 'zod/v4-mini';
+import * as locales from 'zod/v4/locales';
+
+// After
+import { z } from '@oxog/vld';
+import * as core from '@oxog/vld/v4/core';
+import * as mini from '@oxog/vld/v4-mini';
+import * as locales from '@oxog/vld/v4/locales';
+```
+
+Release checks enforce zero missing exports and zero `typeof` mismatches for `zod/v4`, `zod/v4-mini`, `zod/v4/mini`, `zod/v4/core`, and `zod/v4/locales` against the installed latest Zod.
+
+### Real App Drop-in Verification
+
+`npm run verify:drop-in` creates two temporary TypeScript applications from the same fixture:
+
+- One imports and runs against real `zod`.
+- One imports and runs against the locally built `@oxog/vld` package.
+- The fixture exercises root APIs, `v4`, `v4-mini`, `v4/core`, `v4/locales`, parsing, error formatting, JSON Schema output, mini helpers, and core factories.
+- The normalized runtime outputs must match exactly.
+
+## Benchmarks
+
+### Performance Results
+
+Median of 11 samples per case against Zod 4.4.3, the latest stable release at the time of measurement. The release gate also runs focused runtime, startup, memory, package, install, security, Zod parity, and real drop-in app checks before publishing.
+
+| Test Case | VLD Median Performance | Improvement |
+|-----------|----------------|-------------|
+| Simple String | 719.2M ops/sec | **3.40x faster** |
+| Email Validation | 22.1M ops/sec | **2.87x faster** |
+| Top-level Email Format | 22.8M ops/sec | **3.66x faster** |
+| StringBool Validation | 32.7M ops/sec | **3.44x faster** |
+| Number Validation | 226.2M ops/sec | **27.62x faster** |
+| Simple Object | 37.7M ops/sec | **1.40x faster** |
+| Complex Object | 2.3M ops/sec | **1.02x faster** |
+| Array Validation | 39.8M ops/sec | **6.74x faster** |
+| Union Types | 38.1M ops/sec | **4.10x faster** |
+| Optional Values | 236.9M ops/sec | **7.57x faster** |
+| Nullable Values | 224.7M ops/sec | **10.71x faster** |
+| Nullish Values | 228.4M ops/sec | **52.92x faster** |
+| Default Values | 207.8M ops/sec | **9.71x faster** |
+| Catch Values | 232.1M ops/sec | **46.58x faster** |
+| SafeParse | 162.0M ops/sec | **1.80x faster** |
+| Type Coercion | 204.5M ops/sec | **8.72x faster** |
+| Enum Validation | 180.3M ops/sec | **1.32x faster** |
+| Discriminated Union | 19.2M ops/sec | **1.79x faster** |
+| Tuple Validation | 50.0M ops/sec | **7.99x faster** |
+| Record Validation | 10.7M ops/sec | **5.63x faster** |
+| Set Validation | 18.9M ops/sec | **1.84x faster** |
+| Map Validation | 14.8M ops/sec | **2.37x faster** |
+| BigInt Validation | 164.8M ops/sec | **14.88x faster** |
+| Date Validation | 227.2M ops/sec | **2.57x faster** |
+| Symbol Validation | 230.0M ops/sec | **1.01x faster** |
+| Any Validation | 232.5M ops/sec | **1.01x faster** |
+| Unknown Validation | 234.9M ops/sec | **1.04x faster** |
+| Function Validation | 233.6M ops/sec | **3.52x faster** |
+| Template Literal Validation | 39.3M ops/sec | **1.15x faster** |
+| Promise Async Validation | 6.3M ops/sec | **1.38x faster** |
+
+**VLD won 30/30 snapshot tests. Release checks additionally enforce runtime, startup, memory, Zod subpath parity, and real drop-in app guard thresholds against Zod.**
+
+### Run Benchmarks
+
+```bash
+# Quick performance comparison
+npm run benchmark
+
+# Median-based stable comparison
+npm run benchmark:stable
+
+# Fast CI-friendly performance regression guard
+npm run benchmark:guard
+
+# Full release gate: lint, source and published types, tests, exports, package and install checks, security audit, Zod parity, real drop-in app verification, and performance guards
+npm run release:check
+
+# Memory usage comparison
+npm run benchmark:memory
+
+# Startup time comparison
+npm run benchmark:startup
+
+# Run all benchmarks
+npm run benchmark:all
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Links
+
+- [Documentation](https://vld.oxog.dev)
+- [NPM Package](https://www.npmjs.com/package/@oxog/vld)
+- [GitHub Repository](https://github.com/ersinkoc/vld)
+
+---
+
+Made with Love by [Ersin KOC](https://github.com/ersinkoc)