A modern, TypeScript-first alternative to Lodash with superior performance, type safety, and bundle optimization.

Quick Start • Performance • Technical Deep Dive • API Reference • Migration Guide

---

As they say...

"When in doubt in JavaScript, just use lodash."

But what if there was something better?

Meet Highdash — the next step up from lodash. 🚀

---

🚀 Why Highdash?

While Lodash has been the go-to utility library for JavaScript developers, it was built for a different era. Highdash addresses the modern challenges that Lodash struggles with:

❌ Lodash Limitations

• Legacy JavaScript: Built for ES5, missing modern optimizations
• Poor Tree-Shaking: Large bundle sizes even when importing single functions
• Type Safety Issues: Generic types often lose precision
• Performance Overhead: Older algorithms and patterns
• Bundle Bloat: ~70KB minified + gzipped for full library
• Side Effects: Some functions have hidden mutations
• Outdated Dependencies: Relies on legacy polyfills

✅ Highdash Advantages

• Modern ES2020+: Leverages latest JavaScript features for optimal performance
• Perfect Tree-Shaking: Import only what you need, pay only for what you use
• TypeScript-First: Built with TypeScript from the ground up
• Superior Performance: 2-5x faster in many operations
• Tiny Bundle Size: Main index only 1.9KB gzipped
• Zero Dependencies: No external package dependencies
• Pure Functions: No hidden side effects or mutations
• Future-Proof: Designed for modern bundlers and environments

---

📊 Performance Comparison

Operation	Lodash	Highdash	Improvement
cloneDeep (complex)	11ms	2.6ms	4.4x faster
isEqual (deep objects)	12.6ms	8ms	1.6x faster
merge (mutable)	4.2ms	1ms	4.2x faster
mergeDeep (immutable)	4ms	1ms	4.0x faster
orderBy (2 keys)	36.6ms	31ms	1.2x faster
flattenDeep (nested arrays)	6.2ms	3ms	2.1x faster
pick (object properties)	1.8ms	0.6ms	3.0x faster
omit (object properties)	42.6ms	35.6ms	1.2x faster
values (object values)	17.2ms	2.2ms	7.8x faster

Benchmarks run on Node.js 18+, 1000 iterations. Results averaged over 5 runs.

💡 Want to verify these results? Run the benchmarks yourself:

npm run benchmark:compare

This will run comprehensive performance tests comparing Highdash with Lodash on your machine.

🔍 Want to understand WHY Highdash is faster? Check out our Technical Comparison for detailed implementation analysis and optimization strategies.

📏 Bundle Size Details

Here are the actual measured bundle sizes:

Library	Raw Size	Gzipped Size	What's Included
Highdash (main index)	10,705 bytes (10.7KB)	1,915 bytes (1.9KB)	All functions in single file
Lodash (main index)	~24,000 bytes (24KB)	~8,000 bytes (8KB)	All functions in single file
Highdash (full library)	~60,000 bytes (60KB)	~13,500 bytes (13.5KB)	Complete package
Lodash (full library)	73,015 bytes (73KB)	25,941 bytes (25.9KB)	Complete package

Comparison Analysis:

• Highdash vs Lodash (main index): 4.2x smaller gzipped (1.9KB vs 8KB)
• Highdash vs Lodash (full library): 1.9x smaller gzipped (13.5KB vs 25.9KB)

🔍 Check current sizes: Run npm run size:gzip to see live measurements

---

📦 Installation

npm install highdash
# or
yarn add highdash
# or
pnpm add highdash

---

🎯 Quick Start

Tree-Shakable Imports

// ✅ Import only what you need (recommended)
import { debounce, isEqual, groupBy } from 'highdash';

// ✅ Import from subpaths for maximum tree-shaking
import { debounce } from 'highdash/core/debounce.js';
import { isEqual } from 'highdash/lang/isEqual.js';

// ❌ Avoid importing everything (defeats tree-shaking)
import * as _ from 'highdash';

CommonJS Support

Highdash supports both ESM and CommonJS imports. For CommonJS projects:

// CommonJS require (use .cjs extension for .js files)
const { debounce, isEqual } = require('highdash');

// Tree-shakable CommonJS imports
const { debounce } = require('highdash/core/debounce');
const { isEqual } = require('highdash/lang/isEqual');

Note: If your project uses "type": "module" in package.json, use .cjs extension for CommonJS files or use dynamic imports.

Core Examples

import { debounce, isEqual, groupBy, cloneDeep } from 'highdash';

// Debounce with modern options
const debounced = debounce((value: string) => {
  console.log('Searching for:', value);
}, 300, { leading: true, trailing: true });

// Deep equality with cycle detection
const equal = isEqual(
  { users: [{ name: 'John' }] },
  { users: [{ name: 'John' }] }
); // true

// Group with type safety
const users = [
  { name: 'John', age: 25, active: true },
  { name: 'Jane', age: 30, active: false },
  { name: 'Bob', age: 25, active: true }
];

const grouped = groupBy(users, 'age');
// Result: { '25': [user1, user3], '30': [user2] }

// Deep clone with symbol support
const original = { data: [1, 2, 3], [Symbol('key')]: 'value' };
const cloned = cloneDeep(original);

---

🔥 Modern Features

Enhanced Type Safety

// Lodash loses type information
const lodashResult = _.groupBy(users, 'age'); // any[]

// Highdash preserves types
const highdashResult = groupBy(users, 'age'); // Record<string, User[]>

Modern JavaScript Integration

// Uses native Array.flat() instead of custom implementation
const flattened = flattenDeep([[1, [2, [3]]]]); // [1, 2, 3]

// Leverages Object.fromEntries for better performance
const mapped = mapValues({ a: 1, b: 2 }, x => x * 2); // { a: 2, b: 4 }

// Uses Set for efficient deduplication
const unique = uniq([1, 1, 2, 2, 3, 3]); // [1, 2, 3]

Advanced Function Utilities

import { pDebounce, pThrottle, retry, timeout } from 'highdash';

// Promise-aware debounce
const searchAPI = pDebounce(async (query: string) => {
  const response = await fetch(`/api/search?q=${query}`);
  return response.json();
}, 300);

// Retry with exponential backoff
const fetchData = retry(async () => {
  const response = await fetch('/api/data');
  if (!response.ok) throw new Error('Failed');
  return response.json();
}, { retries: 3, factor: 2 });

// Timeout wrapper
const result = await timeout(fetchData(), 5000, 'Request timed out');

---

🔄 Migrating from Lodash

1. Update Imports

// Before (Lodash)
import _ from 'lodash';
import { debounce } from 'lodash';

// After (Highdash)
import { debounce } from 'highdash';
// or
import { debounce } from 'highdash/core/debounce.js';

2. Update Function Calls

// Most functions are drop-in replacements
const result = groupBy(users, 'age'); // Same API

// Some functions have enhanced options
const debounced = debounce(func, 300, { 
  leading: true,  // New option
  trailing: true,
  maxWait: 1000   // New option
});

3. Leverage New Features

// Use promise-aware functions
const searchAPI = pDebounce(async (query) => {
  return await fetch(`/api/search?q=${query}`);
}, 300);

// Use immutable operations
const updated = mergeDeep(state, { user: { name: 'John' } });

// Use retry for resilience
const data = await retry(fetchData, { retries: 3 });

---

🏗 Bundle Optimization

Tree-Shaking Configuration

// webpack.config.js
module.exports = {
  optimization: {
    usedExports: true,
    sideEffects: false, // Highdash is side-effect free
  },
};

// rollup.config.js
export default {
  treeshake: {
    moduleSideEffects: false,
  },
};

Bundle Analysis

# Analyze bundle size
npm run analyze

# Check gzipped sizes
npm run size:gzip

Import Strategies

// ✅ Optimal: Individual imports
import { debounce } from 'highdash/core/debounce.js';

// ✅ Good: Namespace imports
import { debounce, throttle } from 'highdash';

// ❌ Avoid: Full library import
import * as _ from 'highdash';

---

🧪 Testing

# Run tests
npm test

# Run with coverage
npm test -- --coverage

# Run benchmarks
npm run benchmark:compare

Test Coverage

• 2000+ tests across all functions
• 91%+ code coverage with comprehensive edge cases
• Type safety validation with TypeScript strict mode
• Performance benchmarks against Lodash

---

🚀 Development

Prerequisites

• Node.js 18+
• npm/yarn/pnpm

Setup

git clone https://github.com/dev-ahmadbilal/highdash.git
cd highdash
npm install

Scripts

# Development
npm run build          # Build for development
npm run build:prod     # Build for production (optimized)
npm run test           # Run tests
npm run lint           # Lint code

# Analysis
npm run analyze        # Bundle size analysis
npm run size           # Size overview
npm run size:gzip      # Gzipped sizes

# Benchmarking
npm run benchmark      # Run benchmarks
npm run benchmark:compare  # Compare with Lodash

---

📈 Roadmap

✅ Completed

• Core utility functions (228 functions)
• TypeScript-first implementation
• Tree-shaking optimization
• Performance benchmarks
• Comprehensive testing
• Bundle size optimization
• Modern JavaScript features
• Promise-aware utilities

🚧 In Progress

• Documentation website
• Migration tools
• Performance monitoring
• Additional utility functions

🔮 Planned

• Browser compatibility matrix
• Performance regression testing
• Advanced tree-shaking optimizations
• WebAssembly acceleration for heavy operations

---

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

---

📄 License

MIT License - see LICENSE for details.

---

Contact

If you have any questions, suggestions, or would like to collaborate, please feel free to reach out:

• Email: [email protected]
• LinkedIn: Ahmad Bilal

I look forward to hearing from you!

---

🙏 Acknowledgments

• Lodash - The original inspiration and foundation
• TypeScript Team - For the amazing type system
• Modern JavaScript - For the powerful native APIs
• Open Source Community - For the continuous support

---

Made with ❤️ by the Ahmad Bilal