@zerovoids/utils

Modern utility library for TypeScript

Features • Installation • Modules • Documentation

✨ Features

• 🎯 Type-Safe - Full TypeScript support with comprehensive type definitions
• 📦 Tree-Shakable - Import only what you need, optimized bundle size
• 🔄 Dual Package - Works seamlessly with both ESM and CommonJS
• ⚡ Zero Dependencies - Lightweight with no external dependencies
• ✅ Well Tested - Comprehensive test coverage with Vitest
• 🎨 Modern Codebase - Built with the latest JavaScript features

📦 Installation

# npm
npm install @zerovoids/utils

# pnpm
pnpm add @zerovoids/utils

# yarn
yarn add @zerovoids/utils

📚 Modules

📊 Number Utils

Advanced number formatting and precision rounding utilities.

import { formatNumber, toBankersRound, roundHalfAwayFromZero } from '@zerovoids/utils/number';

// Adaptive formatting - perfect for charts and visualizations
formatNumber(0.0000345, { mode: 'adaptive', decimals: 2 });
// → "0.00003"

formatNumber(1234.5678, { mode: 'adaptive', decimals: 2 });
// → "1,234.57"

// Fixed decimal places with custom affixes
formatNumber(1234567.89, { 
  mode: 'fixed',
  decimals: 2,
  prefix: { text: '$', space: false },
  suffix: { text: 'USD', space: true }
});
// → "$1,234,567.89 USD"

// Banker's rounding (IEEE 754) - reduces cumulative rounding bias
toBankersRound(2.5, { precision: 0 }); // → 2 (rounds to even)
toBankersRound(3.5, { precision: 0 }); // → 4 (rounds to even)

// Commercial rounding (round half away from zero)
roundHalfAwayFromZero(2.5, { precision: 0 });  // → 3
roundHalfAwayFromZero(-2.5, { precision: 0 }); // → -3

Features:

• Multiple formatting modes: adaptive, fixed, auto, raw
• Precision rounding methods: banker's round, commercial round
• Customizable prefixes and suffixes with spacing control
• Locale-aware number formatting
• Handles edge cases and tiny/large numbers

⚡ Unit Conversion

Flexible unit conversion utilities optimized for data visualization and dashboards.

import { 
  convertUnitFromTo, 
  convertUnitToFit, 
  getOptimalUnit 
} from '@zerovoids/utils/unit';

// Direct unit conversion
convertUnitFromTo({ 
  number: 5000, 
  unit: 'mass', 
  from: 'g', 
  to: 'kg' 
});
// → { number: 5, unit: 'mass', suffix: 'kg' }

// Auto-fit to most appropriate unit
convertUnitToFit({ 
  number: 500, 
  unit: 'mass', 
  from: 'g' 
});
// → { number: 500, unit: 'mass', suffix: 'g' }

convertUnitToFit({ 
  number: 5000, 
  unit: 'mass', 
  from: 'g' 
});
// → { number: 5, unit: 'mass', suffix: 'kg' }

// Find optimal unit for multiple values (perfect for charts)
getOptimalUnit({ 
  numbers: [500, 1500, 2500], 
  unit: 'mass', 
  from: 'g' 
});
// → 'g' (keeps all values in same scale)

getOptimalUnit({ 
  numbers: [5000, 15000, 25000], 
  unit: 'mass', 
  from: 'g' 
});
// → 'kg' (converts for better readability)

Built-in Units:

• Mass: g, kg, ton (gap: 3 → 1000x between units)
• Area: cm², m², km² (gap: 6 → 1,000,000x between units)
• Volume: mL, L, kL (gap: 3 → 1000x between units)
• Data: B, KB, MB, GB, TB, PB (gap: 3 → 1000x between units)
• Count: "", K, M, B, T (gap: 3 → 1000x between units, for large numbers like 5K, 2.5M)

Custom Units:

// Define your own units with custom gap
const customUnitMap = {
  energy: { 
    gap: 3, 
    suffices: ['Wh', 'kWh', 'MWh', 'GWh'], 
    baseIndex: 1 
  },
  temperature: { 
    gap: 3, 
    suffices: ['mK', 'K', 'kK'], 
    baseIndex: 1 
  }
};

convertUnitToFit({ 
  number: 5000, 
  unit: 'energy', 
  from: 'Wh',
  unitMap: customUnitMap
});
// → { number: 5, unit: 'energy', suffix: 'kWh' }

Features:

• Smart auto-conversion to optimal units
• Consistent unit selection for chart datasets
• Fully customizable unit mappings
• Precision handling with banker's rounding
• Support for various optimization strategies (min, max, freq)

🎯 Why @zerovoids/utils?

Unlike general-purpose libraries (lodash, ramda), @zerovoids/utils provides specialized utilities that solve specific problems:

| Problem | Solution | |---------|----------| | Chart numbers with varying magnitudes | formatNumber with adaptive mode | | Financial calculations with rounding bias | toBankersRound (IEEE 754) | | Dashboard unit consistency | Smart unit conversion with getOptimalUnit | | File size formatting | Built-in data units (B, KB, MB, GB, etc.) | | Large number abbreviations | Count units (K, M, B, T) |

🎨 Usage Examples

Chart Data Formatting

import { formatNumber } from '@zerovoids/utils/number';

const chartData = [0.00012, 1.5, 1234.567, 999999];

const formatted = chartData.map(value => 
  formatNumber(value, { mode: 'adaptive', decimals: 2 })
);
// → ["0.00012", "1.5", "1,234.57", "999,999"]

Weight Dashboard

import { convertUnitToFit, getOptimalUnit } from '@zerovoids/utils/unit';

// Auto-convert individual values
const weight = convertUnitToFit({ 
  number: 5420, 
  unit: 'mass', 
  from: 'g' 
});
// → { number: 5.42, unit: 'mass', suffix: 'kg' }

// Find optimal unit for chart axis
const chartValues = [4500, 8200, 12000, 15800];
const optimalUnit = getOptimalUnit({ 
  numbers: chartValues, 
  unit: 'mass', 
  from: 'g' 
});
// → 'kg'

// Convert all values to optimal unit
const chartData = chartValues.map(value => 
  convertUnitFromTo({ 
    number: value, 
    unit: 'mass', 
    from: 'g', 
    to: optimalUnit 
  })
);
// → All values converted to kg for consistent display

File Size Formatting

import { convertUnitToFit } from '@zerovoids/utils/unit';

const fileSizes = [1024, 1048576, 1073741824];

const formatted = fileSizes.map(bytes => 
  convertUnitToFit({ number: bytes, unit: 'data', from: 'B' })
);
// → [
//   { number: 1.024, unit: 'data', suffix: 'KB' },
//   { number: 1.049, unit: 'data', suffix: 'MB' },
//   { number: 1.074, unit: 'data', suffix: 'GB' }
// ]

Large Number Abbreviation

import { convertUnitToFit, formatNumber } from '@zerovoids/utils/unit';

const followers = 2547893;

const converted = convertUnitToFit({ 
  number: followers, 
  unit: 'count', 
  from: '' 
});
// → { number: 2.548, unit: 'count', suffix: 'M' }

const formatted = formatNumber(converted.number, { 
  mode: 'fixed', 
  decimals: 1,
  suffix: { text: converted.suffix, space: false }
});
// → "2.5M"

📖 Documentation

Detailed API documentation is coming soon.

🛠️ Development

# Install dependencies
pnpm install

# Run tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Build
pnpm build

# Lint and format
pnpm check

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT © zerovoids

🔗 Links

• npm package
• GitHub repository
• Issue tracker

Made with ❤️ by zerovoids