auto-unit

AutoUnit

English documentation is translated by AI. If you have any questions about the content, please refer to the Chinese document. Contributions to improve translations are welcome.

AutoUnit is a utility class for automatic unit conversion, supporting custom unit systems, thresholds, and decimal place configurations.

• Automatically selects appropriate units to output formatted strings
• Reverse parses numeric values from unit-formatted strings
• Quickly build any unit system
• Supports high-precision calculations
• Supports calculations beyond JS safe number ranges

Quick Links

• Quick Start
• Best Practices
• API
• Contributing

Quick Start

• Fixed-base Units

import AutoUnit from 'auto-unit';

const autoUnit = new AutoUnit([ 'B', 'KB', 'MB', 'GB', 'TB', 'PB' ], {
  baseDigit: 1024,
})

console.log(autoUnit.format(1024 * 1024 * 100)) // 100MB

The baseDigit parameter represents the conversion base between units. For example, 1024 means 1KB equals 1024 bytes.

• Variable-base Units

import AutoUnit from 'auto-unit';

const autoUnit = new AutoUnit([ 'mm', 10, 'cm', 100, 'm', 1e3, 'km' ])

console.log(autoUnit.format(1000)) // 1m

You can customize conversion bases between units. For example, [ 'mm', 10, 'cm', 100, 'm', 1e3, 'km' ] means: 1 cm equals 10 mm, 1 m equals 100 cm, and 1 km equals 1000 m.

• High Precision & Large Integers

import AutoUnit from 'auto-unit';

const units = [ 'mm', 10, 'cm', 100, 'm', 1e3, 'km', 1e3, 'Mm', 1e3, 'Gm', 1e3, 'Tm' ]
const autoUnit = new AutoUnit(units, { highPrecision: true })

console.log(autoUnit.format(1e18)) // 1000Tm

The highPrecision parameter enables high-precision mode using decimal.js. It supports number, string, BigInt, and Decimal inputs.

Best Practices

• For most use cases requiring formatted unit strings, consider wrapping format:

import AutoUnit from 'auto-unit';

const autoUnit = new AutoUnit([ 'B', 'KB', 'MB', 'GB', 'TB', 'PB' ], {
  baseDigit: 1024,
})

export const formatFileSize = (num: number) => {
  return autoUnit.format(num)
}

• In modular projects (e.g., React/Vue), pre-initialize unit systems globally (e.g., in utils/units.ts) rather than recreating them per component.

API

Constructor

class AutoUnit {
  constructor(
          readonly units: (string | number)[],
          option: AutoUnitOptions<DS> = {},
  ) {}
}

• Parameters:
  • units: Unit array.
  • option: Configuration options.
    • baseDigit?: Base number for auto-generating unit conversions.
    • threshold?: Unit switch threshold (default: 1).
    • decimal?: Decimal configuration (fixed number or range format).
    • highPrecision?: Enables decimal.js for precise calculations.

Methods

getUnit(num: Num<DS>)

Gets the optimal unit and converted value from base units.

• Parameters:

  • num: Input number. Supports number, string, BigInt, and Decimal in high-precision mode.

• Returns:

  • { num: number, unit: string, decimal: Decimal }: Converted value with unit. Includes Decimal in high-precision mode.

format(num: Num<DS>, decimal = this.decimal)

Formats a number into a unit-string representation.

• Parameters:

  • num: Input number (supports extended types in high-precision mode).
  • decimal?: Overrides default decimal configuration.

• Returns:

  • Formatted string with value and unit.

toBase(num: Num<DS>, unit: string)

Converts a unit-formatted number back to base units.

• Parameters:

  • num: Input value in specified unit.
  • unit: Current unit.

• Returns:

  • Converted value in base units (number or Decimal).

splitUnit(str: string)

Extracts numeric value and unit from a string.

• Parameters:

  • str: Input string containing value and unit.

• Returns:

  • { num: number, unit: string, decimal: Decimal }: Parsed components with Decimal in high-precision mode.

parse(str: string)

Converts a unit-formatted string to base unit value.

• Parameters:

  • str: Input string.

• Returns:

  • Converted value in base units (number or Decimal).

fromUnitFormat(num: number, unit: string, decimal?: DecimalPlace)

Converts between units and formats with specified decimals.

• Parameters:

  • num: Input value.
  • unit: Source unit.
  • decimal?: Overrides default decimal configuration.

• Returns:

  • Formatted string with converted value and unit.

Contributing

Contributions of all forms are welcome, including bug reports, documentation improvements, translation updates, and test enhancements.