https://github.com/flycran/auto-unit
Automatically select the appropriate unit of measurement
https://github.com/flycran/auto-unit
Last synced: about 1 month ago
JSON representation
Automatically select the appropriate unit of measurement
- Host: GitHub
- URL: https://github.com/flycran/auto-unit
- Owner: flycran
- License: mit
- Created: 2023-11-22T06:53:08.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2026-03-14T03:28:48.000Z (3 months ago)
- Last Synced: 2026-03-14T14:56:40.033Z (3 months ago)
- Language: TypeScript
- Size: 86.9 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# AutoUnit
English documentation is translated by AI. If you have any questions about the content, please refer to the [Chinese document](./README.zh.md). 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](#quick-start)
- [Best Practices](#best-practices)
- [API](#api)
- [Contributing](#contributing)
## Quick Start
- **Fixed-base Units**
```ts
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**
```ts
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**
```ts
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`:
```ts
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**
```ts
class AutoUnit {
constructor(
readonly units: (string | number)[],
option: AutoUnitOptions = {},
) {}
}
```
- **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)`
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, 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, 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.