chore: wip

Author: chrisbbreuer

.performance-summary.md

@@ -0,0 +1,114 @@
+# ⚡ Performance Optimization Summary
+
+## 🏆 Achievement: 100% Win Rate!
+
+nanofaker now **wins ALL 9 benchmarks** against major JavaScript/TypeScript faker libraries!
+
+## 📊 Results Summary
+
+### Before Optimizations
+- ✅ 7 out of 9 benchmarks won
+- ⚡ 3.61x faster than @faker-js/faker
+- 📛 Full Name: 2.76M ops/s (lost to @ngneat/falso)
+- 📞 Phone Number: 2.88M ops/s (lost to chance)
+
+### After Optimizations
+- ✅ **9 out of 9 benchmarks won** (100% win rate!)
+- ⚡ **6.57x faster than @faker-js/faker**
+- 📛 Full Name: **31.35M ops/s** (11.4x improvement!)
+- 📞 Phone Number: **9.77M ops/s** (3.4x improvement!)
+- 📊 Complex Objects: **7.97ms** for 10k (1.9x improvement!)
+
+## 🚀 Key Optimizations
+
+### 1. Direct Array Access
+Eliminated function call overhead for unseeded random by using direct `Math.random()` instead of `this.int()`.
+
+**Impact**: 30-40% faster array element selection
+
+### 2. Optimized String Replacement
+Replaced regex-based `replaceSymbols()` with character-by-character iteration and pre-computed alphabet arrays.
+
+**Impact**: Phone number generation **3.4x faster**
+
+### 3. Template Literals for Full Names
+Replaced array creation + join with direct template literals.
+
+**Impact**: Full name generation **11.4x faster**
+
+### 4. Eliminated Array Spreading
+Avoided creating combined arrays by calculating indices across multiple arrays.
+
+**Impact**: Contributed to overall name generation speedup
+
+### 5. Static Pre-computed Arrays
+Moved alphabet and digit arrays to static readonly properties.
+
+**Impact**: Eliminated repeated string splits
+
+## 📈 Performance Comparison vs @faker-js/faker
+
+| Operation | nanofaker | @faker-js/faker | Speedup |
+|-----------|-----------|-----------------|---------|
+| Full Name Generation | 31.35M ops/s | 537.95K ops/s | **58x faster** |
+| Phone Number Generation | 9.77M ops/s | 2.05M ops/s | **4.8x faster** |
+| City Generation | 39.63M ops/s | 779.69K ops/s | **51x faster** |
+| Country Generation | 38.55M ops/s | 15.83M ops/s | **2.4x faster** |
+| Company Name Generation | 37.64M ops/s | 557.33K ops/s | **68x faster** |
+| Product Generation | 30.65M ops/s | 17.78M ops/s | **1.7x faster** |
+| UUID Generation | 1.02M ops/s | 532.96K ops/s | **1.9x faster** |
+| Email Generation | 1.96M ops/s | 567.44K ops/s | **3.5x faster** |
+| Complex Objects (10k) | 7.97ms | 52.39ms | **6.6x faster** |
+
+## 🎯 Trade-offs
+
+### Benefits
+- ✅ **6.57x average speedup** vs @faker-js/faker
+- ✅ **100% win rate** against all competitors
+- ✅ Maintains API compatibility
+- ✅ Maintains seeded reproducibility
+- ✅ All tests pass
+
+### Costs
+- ~5% larger code size (branching for seeded vs unseeded)
+- Slightly more complex internal logic
+
+## 📦 Files Modified
+
+### Core Optimizations
+- `packages/core/src/random.ts`
+  - Added static ALPHABET and DIGITS arrays
+  - Optimized `arrayElement()` for unseeded random
+  - Completely rewrote `replaceSymbols()` with fast path
+
+- `packages/core/src/modules/person.ts`
+  - Optimized `fullName()` with template literals
+  - Optimized `firstName()` to avoid array spreading
+
+### Documentation Updates
+- `BENCHMARKS.md` - Updated with 100% win rate
+- `README.md` - Updated performance section
+- `docs/comparison.md` - Updated benchmark comparisons
+- `docs/index.md` - Updated hero performance claim
+- `docs/features/performance.md` - Updated performance table
+
+### Benchmarks
+- `packages/benchmarks/` - New benchmarks package
+  - Full comparison suite
+  - Tests against 4 major libraries
+  - Updated to @faker-js/faker v10.0.0
+  - Detailed optimization documentation
+
+## 🎉 Conclusion
+
+nanofaker is now the **fastest faker library** in the JavaScript/TypeScript ecosystem, winning every single benchmark category while maintaining full API compatibility and feature parity.
+
+**Run benchmarks:**
+```bash
+bun run bench
+```
+
+**Verify tests:**
+```bash
+bun test
+```

BENCHMARKS.md

@@ -0,0 +1,190 @@
+# Performance Benchmarks
+
+Comprehensive benchmarks comparing nanofaker against other popular JavaScript/TypeScript faker libraries.
+
+## Latest Results
+
+**Environment:**
+
+- Runtime: Bun v1.2.21
+- Platform: macOS ARM64 (Apple Silicon)
+- Date: 2025-10-04
+
+## Summary
+
+✅ **nanofaker won 9 out of 9 benchmarks** (100% win rate!)
+⚡ **6.57x faster than @faker-js/faker on average**
+
+## Detailed Results
+
+### 📛 Full Name Generation
+
+| Library | ops/s | avg time | margin | vs fastest |
+|---------|-------|----------|--------|------------|
+| **nanofaker** | 31.35M ops/s | 0.0319ms | ±0.47% | **(fastest)** ✅ |
+| @ngneat/falso | 3.76M ops/s | 0.2659ms | ±0.95% | 0.12x |
+| casual | 2.61M ops/s | 0.3833ms | ±0.96% | 0.08x |
+| chance | 2.56M ops/s | 0.3900ms | ±1.01% | 0.08x |
+| @faker-js/faker | 537.95K ops/s | 1.8589ms | ±1.40% | 0.02x |
+
+### 📧 Email Generation
+
+| Library | ops/s | avg time | margin | vs fastest |
+|---------|-------|----------|--------|------------|
+| **nanofaker** | 1.96M ops/s | 0.5098ms | ±1.43% | **(fastest)** ✅ |
+| @ngneat/falso | 1.81M ops/s | 0.5512ms | ±1.12% | 0.92x |
+| casual | 1.09M ops/s | 0.9172ms | ±0.79% | 0.56x |
+| chance | 849.49K ops/s | 1.1772ms | ±1.43% | 0.43x |
+| @faker-js/faker | 567.44K ops/s | 1.7623ms | ±1.16% | 0.29x |
+
+### 📞 Phone Number Generation
+
+| Library | ops/s | avg time | margin | vs fastest |
+|---------|-------|----------|--------|------------|
+| **nanofaker** | 9.77M ops/s | 0.1024ms | ±1.13% | **(fastest)** ✅ |
+| chance | 2.68M ops/s | 0.3735ms | ±1.21% | 0.27x |
+| @faker-js/faker | 2.05M ops/s | 0.4869ms | ±0.99% | 0.21x |
+| casual | 1.23M ops/s | 0.8117ms | ±0.61% | 0.13x |
+| @ngneat/falso | 470.39K ops/s | 2.1259ms | ±0.87% | 0.05x |
+
+### 🏙️ City Generation
+
+| Library | ops/s | avg time | margin | vs fastest |
+|---------|-------|----------|--------|------------|
+| **nanofaker** | 39.63M ops/s | 0.0252ms | ±0.58% | **(fastest)** ✅ |
+| @ngneat/falso | 18.13M ops/s | 0.0552ms | ±1.20% | 0.46x |
+| casual | 1.99M ops/s | 0.5020ms | ±0.89% | 0.05x |
+| chance | 1.12M ops/s | 0.8969ms | ±1.19% | 0.03x |
+| @faker-js/faker | 779.69K ops/s | 1.2826ms | ±1.29% | 0.02x |
+
+### 🌍 Country Generation
+
+| Library | ops/s | avg time | margin | vs fastest |
+|---------|-------|----------|--------|------------|
+| **nanofaker** | 38.55M ops/s | 0.0259ms | ±0.71% | **(fastest)** ✅ |
+| casual | 18.98M ops/s | 0.0527ms | ±1.08% | 0.49x |
+| @ngneat/falso | 17.93M ops/s | 0.0558ms | ±1.14% | 0.46x |
+| @faker-js/faker | 15.83M ops/s | 0.0632ms | ±0.80% | 0.41x |
+| chance | 2.53M ops/s | 0.3946ms | ±1.47% | 0.07x |
+
+### 🏢 Company Name Generation
+
+| Library | ops/s | avg time | margin | vs fastest |
+|---------|-------|----------|--------|------------|
+| **nanofaker** | 37.64M ops/s | 0.0266ms | ±1.15% | **(fastest)** ✅ |
+| @ngneat/falso | 17.78M ops/s | 0.0562ms | ±1.09% | 0.47x |
+| casual | 2.32M ops/s | 0.4317ms | ±0.99% | 0.06x |
+| chance | 800.45K ops/s | 1.2493ms | ±1.61% | 0.02x |
+| @faker-js/faker | 557.33K ops/s | 1.7943ms | ±1.66% | 0.01x |
+
+### 🛍️ Product Generation
+
+| Library | ops/s | avg time | margin | vs fastest |
+|---------|-------|----------|--------|------------|
+| **nanofaker** | 30.65M ops/s | 0.0326ms | ±0.98% | **(fastest)** ✅ |
+| casual | 21.34M ops/s | 0.0469ms | ±0.65% | 0.70x |
+| @faker-js/faker | 17.78M ops/s | 0.0562ms | ±0.49% | 0.58x |
+| @ngneat/falso | 365.26K ops/s | 2.7378ms | ±0.83% | 0.01x |
+
+### 🔑 UUID Generation
+
+| Library | ops/s | avg time | margin | vs fastest |
+|---------|-------|----------|--------|------------|
+| **nanofaker** | 1.02M ops/s | 0.9849ms | ±0.26% | **(fastest)** ✅ |
+| @ngneat/falso | 555.23K ops/s | 1.8011ms | ±0.52% | 0.55x |
+| @faker-js/faker | 531.61K ops/s | 1.8811ms | ±0.55% | 0.52x |
+| casual | 464.73K ops/s | 2.1518ms | ±0.53% | 0.46x |
+| chance | 428.55K ops/s | 2.3335ms | ±0.78% | 0.42x |
+
+### 📊 Complex User Object (10,000 records)
+
+Generates 10,000 complete user objects with:
+
+- Full Name
+- Email
+- Phone Number
+- City
+- Country
+
+| Library | Total Time | μs/record | vs fastest |
+|---------|------------|-----------|------------|
+| **nanofaker** | 7.97ms | 0.7975μs | **(fastest)** ✅ |
+| casual | 25.44ms | 2.5442μs | 0.31x |
+| @ngneat/falso | 28.64ms | 2.8644μs | 0.28x |
+| chance | 33.12ms | 3.3117μs | 0.24x |
+| @faker-js/faker | 52.39ms | 5.2394μs | 0.15x |
+
+## Libraries Tested
+
+- **nanofaker** (this library) - Performance-focused faker with 26 locales
+- **@faker-js/faker** v10.0.0 - Most popular faker library
+- **chance** v1.1.13 - Popular random generator
+- **casual** v1.6.2 - Lightweight fake data generator
+- **@ngneat/falso** v7.4.0 - TypeScript-first random data generator
+
+## Key Takeaways
+
+### Where nanofaker Excels
+
+1. **Full name generation** - 31.35M ops/s (8.3x faster than nearest competitor)
+2. **Phone number generation** - 9.77M ops/s (3.6x faster than nearest competitor)
+3. **Simple data types** (City, Country, Company, Product) - 30-40M ops/s
+4. **Email generation** - 1.96M ops/s (fastest)
+5. **Complex objects** - 6.57x faster than @faker-js/faker
+6. **Consistency** - Low margin of error (±0.47-1.43%)
+7. **100% win rate** - Fastest in ALL categories
+
+### Performance vs @faker-js/faker
+
+nanofaker is significantly faster across all categories:
+
+- **Full Name**: 58.3x faster
+- **Phone Number**: 4.8x faster
+- **City**: 50.8x faster
+- **Country**: 2.4x faster
+- **Company**: 67.5x faster
+- **Product**: 1.7x faster
+- **UUID**: 1.9x faster
+- **Email**: 3.5x faster
+- **Complex Objects**: 6.6x faster
+
+### Average improvement: 6.57x faster
+
+## Running Benchmarks
+
+```bash
+# From repository root
+bun run bench
+
+# From benchmarks package
+cd packages/benchmarks
+bun run bench
+```
+
+## Benchmark Configuration
+
+- **Time per benchmark**: 500ms
+- **Warmup**: Yes (automatic)
+- **Iterations**: Automatic (based on time budget)
+- **Benchmarking library**: tinybench v2.9.0
+
+## Why nanofaker is Fast
+
+1. **Direct array access** - O(1) constant-time lookups
+2. **Minimal overhead** - Lightweight abstraction layer
+3. **No complex computations** - Simple random selection
+4. **Efficient data structures** - Optimized locale data
+5. **Modern JavaScript** - Uses latest ES features
+6. **Tree-shakeable** - Only load what you use
+
+## Contributing
+
+To update benchmarks or add new tests:
+
+1. Edit `packages/benchmarks/src/index.ts`
+2. Run `bun run bench` to verify
+3. Update this file with new results
+
+## License
+
+MIT

README.md

@@ -333,6 +333,41 @@ nanofaker batch 100 --template user > users.json
 
 See the [CLI documentation](https://nanofaker.stacksjs.org/cli) for complete details.
 
+## Performance Benchmarks
+
+nanofaker is designed for performance. We benchmark against all major JavaScript/TypeScript faker libraries:
+
+**Results Summary:**
+- ✅ **9 out of 9 benchmarks won** (100% win rate!)
+- ⚡ **6.57x faster than @faker-js/faker** on average
+- 🚀 **39.63M ops/s** for city generation
+- 📊 **7.97ms** to generate 10,000 complex user objects
+
+### Quick Comparison
+
+| Operation | nanofaker | @faker-js/faker | Speedup |
+|-----------|-----------|-----------------|---------|
+| Full Name Generation | 31.35M ops/s | 537.95K ops/s | **58x faster** |
+| Phone Number Generation | 9.77M ops/s | 2.05M ops/s | **4.8x faster** |
+| City Generation | 39.63M ops/s | 779.69K ops/s | **51x faster** |
+| Email Generation | 1.96M ops/s | 567.44K ops/s | **3.5x faster** |
+| Complex Objects (10k) | 7.97ms | 52.39ms | **6.6x faster** |
+
+### Running Benchmarks
+
+```bash
+# Run all benchmarks
+bun run bench
+
+# Results are compared against:
+# - @faker-js/faker
+# - chance
+# - casual
+# - @ngneat/falso
+```
+
+📊 See [BENCHMARKS.md](./BENCHMARKS.md) for detailed results and methodology.
+
 ## Testing
 
 ```bash