This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

npm run build              # TypeScript compilation + fix ESM imports
npm run test:types         # Type check without emitting files

npm test                   # Run Jest tests with enforced coverage thresholds
npm run test -- --watch    # Run tests in watch mode
npm run test -- tests/validators/string.test.ts  # Run specific test file

npm run lint               # ESLint check for TypeScript files
npm run format             # Prettier formatting

npm run benchmark          # Quick performance comparison (vs Zod)
npm run benchmark:stable   # Median-based stable benchmark suite
npm run benchmark:guard    # CI-friendly performance regression guard
npm run benchmark:full     # Full performance suite
npm run benchmark:memory   # Memory usage analysis
npm run benchmark:startup  # Startup time comparison
npm run benchmark:all      # Run all benchmarks
npm run release:check      # Full release gate: lint, source/published types, tests, build, package install, audit, Zod parity, performance guard

• Immutable Validators: All validators are immutable to prevent memory leaks and race conditions
• Zero Dependencies: No external runtime dependencies for maximum performance
• TypeScript-First: Full type inference with strict mode enabled
• Modular Structure: Each validator type in its own module for tree-shaking

src/
-  validators/        # Core validator implementations (base, string, number, etc.)
-  coercion/         # Type coercion validators (string, number, boolean, date, bigint)
-  codecs/           # Bidirectional codec implementations (19 built-in codecs)
-  locales/          # 27+ language translations (types.ts defines message templates)
-  utils/            # Utilities (deep-merge, ip-validation, security, codec-utils)
-  errors.ts         # VldError class and formatting utilities (treeify, prettify, flatten)
-  index.ts          # Main API export with factory methods (the `v` object)

All validators extend VldBase<TInput, TOutput> which provides:

• parse(): Validates and returns value or throws
• safeParse(): Returns { success, data } or { success, error }
• Method chaining for composability (refine, transform, default, catch)

Main API uses factory methods (v.string(), v.number()) that return new validator instances to ensure immutability.

Three error formats for different use cases:

• treeifyError(): Nested structure for complex UIs
• prettifyError(): Human-readable console output
• flattenError(): Simple structure for form validation

• Global locale setting via setLocale()
• All error messages support 27+ languages
• Fallback to English for unsupported locales

• Jest with ts-jest for ESM support
• 100% statement, branch, function, and line coverage thresholds enforced
• Test files in tests/ directory mirror source structure:
  • tests/validators/ - Individual validator tests
  • tests/coercion/ - Type coercion tests
  • tests/codecs/ - Codec functionality tests
  • tests/utils/ - Utility function tests
• Focus on edge cases, type coercion, and error messages

1. TypeScript compilation to ES2020 modules
2. Post-build script (scripts/fix-imports.js) adds .js extensions for ESM compatibility
3. Both CommonJS and ESM exports supported via package.json exports field

• Optimized for V8 engine with inline type checks
• Pre-computed keys with Set for O(1) lookups in object validation
• Simplified regex patterns for email/URL validation
• SafeParse optimized to avoid try-catch overhead when possible

VLD includes a comprehensive codec system for bidirectional data transformations:

• VldCodec: Base codec validator class supporting encode/decode operations
• Built-in Codecs: 19 ready-to-use Zod-compatible codecs
• Codec Utils: Cross-platform utility functions for common transformations
• Type Safety: Full TypeScript support with bidirectional type inference

1. String Conversions: stringToNumber, stringToInt, stringToBigInt, stringToBoolean
2. Date Conversions: isoDatetimeToDate, epochSecondsToDate, epochMillisToDate
3. JSON/Complex: jsonCodec, base64Json, jwtPayload
4. URLs: stringToURL, stringToHttpURL, uriComponent
5. Binary Data: base64ToBytes, hexToBytes, utf8ToBytes, etc.

• Circular Dependency Avoidance: Codecs use direct validator imports to prevent circular references
• Error Handling: Comprehensive error messages in all 27+ supported languages
• Async Support: Both sync and async operations with proper error propagation
• Memory Safety: Immutable codec architecture prevents memory leaks

• All codecs have comprehensive test coverage including edge cases
• Round-trip testing ensures encode/decode consistency
• Async codec testing verifies proper Promise handling
• Error path testing covers all failure modes

When adding new codecs:

1. Use VldCodec.create() with proper input/output validators
2. Implement both decode and encode functions
3. Add comprehensive tests including round-trip verification
4. Update codec exports in both src/codecs/index.ts and src/index.ts
5. Add error messages to all locale files
6. Document usage in README.md and API.md

When creating a new validator type:

1. Create validator class in src/validators/ extending VldBase<TInput, TOutput>
2. Implement required parse() and safeParse() methods
3. Add static create() factory method for immutability
4. Export from src/validators/index.ts
5. Add factory method to v object in src/index.ts
6. Add error messages to all 27+ locale files in src/locales/
7. Create tests in tests/validators/ with edge cases