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

• [x] Core utility functions (228 functions)
• [x] TypeScript-first implementation
• [x] Tree-shaking optimization
• [x] Performance benchmarks
• [x] Comprehensive testing
• [x] Bundle size optimization
• [x] Modern JavaScript features
• [x] 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