smart-unit 1.0.4 → 2.0.0

package/README.md

@@ -8,11 +8,13 @@
 [![test](https://github.com/flycran/smart-unit/workflows/Test/badge.svg)](https://github.com/flycran/smart-unit/actions)
 [![license](https://img.shields.io/npm/l/smart-unit)](./LICENSE)
 
-English | [中文](./README.zh-CN.md)
+<p align="center">
+  English | <a href="./README.zh-CN.md">中文</a> | <a href="https://flycran.github.io/smart-unit/en">Documentation</a>
+</p>
 
 ---
 
-**smart-unit** is a lightweight utility for automatic unit conversion with intelligent formatting.
+**smart-unit** is a lightweight automatic unit conversion tool with intelligent formatting.
 
 ```ts
 import SmartUnit from 'smart-unit';
@@ -27,14 +29,14 @@ size.parse('2.5GB');             // 2684354560
 ## Features
 
 - 🎯 **Smart Formatting** — Automatically selects the optimal unit for display
-- 🔢 **Bidirectional** — Convert to units (`format`) and from units (`parse`)
-- ⚡ **High Performance** — Minimal overhead, works in Node.js and browsers
-- 🧮 **High Precision** — Optional `decimal.js` integration for arbitrary precision
-- 📦 **TypeScript First** — Full type safety
-- 🪶 **Lightweight** — Core functionality with minimal footprint
-- ✅ **Well Tested** — Comprehensive test suite with 100% coverage
+- 🔢 **Bidirectional Conversion** — Supports unit formatting (`format`) and reverse parsing (`parse`)
+- ⚡ **High Performance** — Minimal overhead, supports Node.js and browsers
+- 🧮 **High Precision** — Optional `decimal.js` integration for arbitrary precision calculations
+- 📦 **TypeScript First** — Complete type safety
+- 🪶 **Lightweight** — Core functionality with small bundle size
+- ✅ **Well Tested** — 100+ test cases covering various edge cases
 
-## Install
+## Installation
 
 ```bash
 npm install smart-unit
@@ -46,7 +48,7 @@ npm install smart-unit
 
 ## Quick Start
 
-### File Size Formatting
+### Fixed Ratio Units
 
 ```ts
 import SmartUnit from 'smart-unit';
@@ -59,7 +61,7 @@ fileSize.format(1024 * 1024 * 100);  // => "100MB"
 fileSize.format(1536);               // => "1.5KB"
 ```
 
-### Length Units with Variable Ratios
+### Variable Ratio Units
 
 ```ts
 const length = new SmartUnit(['mm', 10, 'cm', 100, 'm', 1000, 'km']);
@@ -68,19 +70,20 @@ length.format(1500);     // => "1.5m"
 length.format(1500000);  // => "1.5km"
 ```
 
-### High-Precision & BigInt Support
+### High Precision & BigInt Support
 
 ```ts
-const bigLength = new SmartUnit(
-  ['mm', 10, 'cm', 100, 'm', 1000, 'km', 1000, 'Mm', 1000, 'Gm', 1000, 'Tm'],
-  { useDecimal: true }
+import { SmartUnitPrecision } from 'smart-unit/precision'
+
+const bigLength = new SmartUnitPrecision(
+  ['mm', 10, 'cm', 100, 'm', 1000, 'km', 1000, 'Mm', 1000, 'Gm', 1000, 'Tm']
 );
 
-// Works with BigInt and numbers beyond JS safe integer range
+// Supports BigInt and values beyond JS safe integer range
 bigLength.format(10n ** 18n);  // => "1000Tm"
 ```
 
-### Parse Unit Strings
+### Parsing Unit Strings
 
 ```ts
 const time = new SmartUnit(['ms', 1000, 's', 60, 'm', 60, 'h']);
@@ -89,160 +92,54 @@ time.parse('90s');   // => 90000 (ms)
 time.parse('2.5h');  // => 9000000 (ms)
 ```
 
-## API
-
-### `new SmartUnit(units, options?)`
-
-Creates a unit converter instance.
-
-#### Parameters
-
-- **units** `(string | number)[]` — Array of unit names and conversion ratios
-  - Even indices: unit names (e.g., `'B'`, `'KB'`)
-  - Odd indices: conversion ratios to next unit (e.g., `1024`)
-- **options** `SmartUnitOptions` — Configuration object
-  - `baseDigit?: number` — Auto-generate ratios (e.g., `1024` for all steps)
-  - `threshold?: number` — Unit switch threshold (default: `1`)
-  - `fractionDigits?: FractionDigits` — Decimal places for formatting
-  - `useDecimal?: boolean` — Enable high-precision mode
-  - `decimalOptions?: Decimal.Config` — Custom decimal.js configuration
-
-#### Methods
-
-##### `.format(num, decimal?)`
-
-Formats a number to the optimal unit string.
-
-```ts
-const size = new SmartUnit(['B', 'KB', 'MB'], { baseDigit: 1024, fractionDigits: 2 });
-
-size.format(1536);           // => "1.50KB"
-size.format(1536, 0);        // => "2KB"
-size.format(1536, '1-3');    // => "1.5KB" (min 1, max 3 decimals)
-```
-
-##### `.parse(str)`
-
-Parses a unit string back to base unit value.
-
-```ts
-const size = new SmartUnit(['B', 'KB', 'MB'], { baseDigit: 1024 });
-
-size.parse('1.5KB');  // => 1536
-size.parse('2MB');    // => 2097152
-```
-
-##### `.getUnit(num)`
-
-Gets the optimal unit and converted value without formatting.
-
-```ts
-const size = new SmartUnit(['B', 'KB', 'MB'], { baseDigit: 1024 });
-
-size.getUnit(1536);
-// => { num: 1.5, unit: 'KB' }
-
-// With high precision
-const precise = new SmartUnit(['B', 'KB', 1024], { useDecimal: true });
-precise.getUnit(1536);
-// => { num: 1.5, unit: 'KB', decimal: Decimal }
-```
-
-##### `.toBase(num, unit)`
-
-Converts a value from specified unit to base unit.
-
-```ts
-const length = new SmartUnit(['mm', 10, 'cm', 100, 'm']);
-
-length.toBase(1.5, 'm');   // => 1500 (mm)
-length.toBase(100, 'cm');  // => 1000 (mm)
-```
-
-##### `.splitUnit(str)`
-
-Extracts numeric value and unit from a formatted string.
-
-```ts
-const size = new SmartUnit(['B', 'KB', 'MB'], { baseDigit: 1024 });
-
-size.splitUnit('1.5KB');  // => { num: 1.5, unit: 'KB' }
-```
-
-##### `.fromUnitFormat(num, unit, decimal?)`
-
-Converts from one unit to the optimal unit and formats.
-
-```ts
-const length = new SmartUnit(['mm', 10, 'cm', 100, 'm', 1000, 'km']);
-
-length.fromUnitFormat(1500, 'm');  // => "1.5km"
-```
-
-## Use Cases
-
-### Data Transfer Rate
-
-```ts
-const bitrate = new SmartUnit(['bps', 'Kbps', 'Mbps', 'Gbps'], {
-  baseDigit: 1000,
-  fractionDigits: 1,
-});
-
-bitrate.format(1500000);  // => "1.5Mbps"
-```
-
-### Frequency
+### Chain Formatting
 
 ```ts
-const freq = new SmartUnit(['Hz', 'kHz', 'MHz', 'GHz'], {
-  baseDigit: 1000,
-  fractionDigits: 2,
-});
+const time = new SmartUnit(['ms', 1000, 's', 60, 'm', 60, 'h']);
 
-freq.format(2400000000);  // => "2.40GHz"
+time.formatChain(63000) // => 1m3s
+time.formatChain(3663000);  // => 1h1m3s
 ```
 
-### Financial Amounts (High Precision)
+### Internationalization
 
 ```ts
-const currency = new SmartUnit(['', 'K', 'M', 'B', 'T'], {
-  baseDigit: 1000,
-  useDecimal: true,
-  fractionDigits: 2,
-});
-
-currency.format('12345678901234567890');  // => "12345678.90T"
-```
+const i18nMap = {
+  ms: 'ms',
+  s: 'seconds',
+  m: 'minutes',
+  h: 'hours',
+}
+const t = (unit: keyof typeof i18nMap) => i18nMap[unit]
 
-## Testing
+const timeI18n = new SmartUnit(['ms', 1000, 's', 60, 'm', 60, 'h'], {
+  separator: ' ',
+}).withConvert(t)
 
-Run the test suite:
-
-```bash
-npm test
+timeI18n.formatChain(90000) // 1minutes 30seconds
+timeI18n.formatChain(9000000) // 2hours 30minutes
 ```
 
-## TypeScript
+## Using TypeScript
 
-smart-unit is written in TypeScript and provides full type safety.
+SmartUnit provides complete type safety support for TypeScript projects.
 
 ```ts
-import SmartUnit from 'smart-unit';
-import type { Decimal } from 'decimal.js';
+import SmartUnit, { type GetUnitNames } from 'smart-unit'
 
-// Regular mode - returns number
-const regular = new SmartUnit(['B', 'KB', 1024]);
-const num: number = regular.parse('1KB');
+const time = new SmartUnit(['ms', 1000, 's', 60, 'm', 60, 'h'])
+// Use utility function to export types
+type TimeUnits = GetUnitNames<typeof time> // => type TimeUnits = "m" | "ms" | "s" | "h"
 
-// High-precision mode - returns Decimal
-const precise = new SmartUnit(['B', 'KB', 1024], { useDecimal: true });
-const dec: Decimal = precise.parse('1KB');
+// The t function must accept all TimeUnits units, otherwise a type error will occur
+const timeI18n = time.withConvert(t)
+// The unit parameter of toBase receives TimeUnits type constraint
+time.toBase(60, 'h')
 ```
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit issues or pull requests.
+Contributions are welcome! Feel free to submit issues or pull requests.
 
 ## License
 

package/README.zh-CN.md

@@ -8,7 +8,9 @@
 [![test](https://github.com/flycran/smart-unit/workflows/Test/badge.svg)](https://github.com/flycran/smart-unit/actions)
 [![license](https://img.shields.io/npm/l/smart-unit)](./LICENSE)
 
-[English](./README.md) | 中文
+<p align="center">
+  <a href="./README.md">English</a> | 中文 | <a href="https://flycran.github.io/smart-unit">完整文档</a>
+</p>
 
 ---
 
@@ -32,7 +34,7 @@ size.parse('2.5GB');             // 2684354560
 - 🧮 **高精度** — 可选 `decimal.js` 集成，支持任意精度计算
 - 📦 **TypeScript 优先** — 完整的类型安全
 - 🪶 **轻量级** — 核心功能，体积小巧
-- ✅ **测试完善** — 全面的测试套件，100% 覆盖率
+- ✅ **测试完善** — 100+ 测试用例，覆盖各种边缘情况
 
 ## 安装
 
@@ -46,7 +48,7 @@ npm install smart-unit
 
 ## 快速开始
 
-### 文件大小格式化
+### 固定比例单位
 
 ```ts
 import SmartUnit from 'smart-unit';
@@ -59,7 +61,7 @@ fileSize.format(1024 * 1024 * 100);  // => "100MB"
 fileSize.format(1536);               // => "1.5KB"
 ```
 
-### 可变进制长度单位
+### 可变比例单位
 
 ```ts
 const length = new SmartUnit(['mm', 10, 'cm', 100, 'm', 1000, 'km']);
@@ -71,9 +73,10 @@ length.format(1500000);  // => "1.5km"
 ### 高精度与 BigInt 支持
 
 ```ts
-const bigLength = new SmartUnit(
-  ['mm', 10, 'cm', 100, 'm', 1000, 'km', 1000, 'Mm', 1000, 'Gm', 1000, 'Tm'],
-  { useDecimal: true }
+import { SmartUnitPrecision } from 'smart-unit/precision'
+
+const bigLength = new SmartUnitPrecision(
+  ['mm', 10, 'cm', 100, 'm', 1000, 'km', 1000, 'Mm', 1000, 'Gm', 1000, 'Tm']
 );
 
 // 支持 BigInt 和超出 JS 安全整数范围的数值
@@ -89,155 +92,49 @@ time.parse('90s');   // => 90000 (ms)
 time.parse('2.5h');  // => 9000000 (ms)
 ```
 
-## API
-
-### `new SmartUnit(units, options?)`
-
-创建单位转换器实例。
-
-#### 参数
-
-- **units** `(string | number)[]` — 单位名称和转换比例数组
-  - 偶数索引：单位名称（如 `'B'`、`'KB'`）
-  - 奇数索引：到下一单位的转换比例（如 `1024`）
-- **options** `SmartUnitOptions` — 配置对象
-  - `baseDigit?: number` — 自动生成比例（如 `1024` 表示所有步骤）
-  - `threshold?: number` — 单位切换阈值（默认：`1`）
-  - `fractionDigits?: FractionDigits` — 格式化小数位数
-  - `useDecimal?: boolean` — 启用高精度模式
-  - `decimalOptions?: Decimal.Config` — 自定义 decimal.js 配置
-
-#### 方法
-
-##### `.format(num, decimal?)`
-
-将数字格式化为最优单位字符串。
-
-```ts
-const size = new SmartUnit(['B', 'KB', 'MB'], { baseDigit: 1024, fractionDigits: 2 });
-
-size.format(1536);           // => "1.50KB"
-size.format(1536, 0);        // => "2KB"
-size.format(1536, '1-3');    // => "1.5KB"（最少1位，最多3位小数）
-```
-
-##### `.parse(str)`
-
-将单位字符串解析回基本单位值。
-
-```ts
-const size = new SmartUnit(['B', 'KB', 'MB'], { baseDigit: 1024 });
-
-size.parse('1.5KB');  // => 1536
-size.parse('2MB');    // => 2097152
-```
-
-##### `.getUnit(num)`
-
-获取最优单位和转换后的值（不进行格式化）。
-
-```ts
-const size = new SmartUnit(['B', 'KB', 'MB'], { baseDigit: 1024 });
-
-size.getUnit(1536);
-// => { num: 1.5, unit: 'KB' }
-
-// 高精度模式
-const precise = new SmartUnit(['B', 'KB', 1024], { useDecimal: true });
-precise.getUnit(1536);
-// => { num: 1.5, unit: 'KB', decimal: Decimal }
-```
-
-##### `.toBase(num, unit)`
-
-将指定单位的值转换为基本单位。
-
-```ts
-const length = new SmartUnit(['mm', 10, 'cm', 100, 'm']);
-
-length.toBase(1.5, 'm');   // => 1500 (mm)
-length.toBase(100, 'cm');  // => 1000 (mm)
-```
-
-##### `.splitUnit(str)`
-
-从格式化字符串中提取数值和单位。
-
-```ts
-const size = new SmartUnit(['B', 'KB', 'MB'], { baseDigit: 1024 });
-
-size.splitUnit('1.5KB');  // => { num: 1.5, unit: 'KB' }
-```
-
-##### `.fromUnitFormat(num, unit, decimal?)`
-
-从一种单位转换到最优单位并格式化。
-
-```ts
-const length = new SmartUnit(['mm', 10, 'cm', 100, 'm', 1000, 'km']);
-
-length.fromUnitFormat(1500, 'm');  // => "1.5km"
-```
-
-## 使用场景
-
-### 数据传输速率
-
-```ts
-const bitrate = new SmartUnit(['bps', 'Kbps', 'Mbps', 'Gbps'], {
-  baseDigit: 1000,
-  fractionDigits: 1,
-});
-
-bitrate.format(1500000);  // => "1.5Mbps"
-```
-
-### 频率
+### 链式单位
 
 ```ts
-const freq = new SmartUnit(['Hz', 'kHz', 'MHz', 'GHz'], {
-  baseDigit: 1000,
-  fractionDigits: 2,
-});
+const time = new SmartUnit(['ms', 1000, 's', 60, 'm', 60, 'h']);
 
-freq.format(2400000000);  // => "2.40GHz"
+time.formatChain(63000) // => 1m3s
+time.formatChain(3663000);  // => 1h1m3s
 ```
 
-### 金融金额（高精度）
+### 国际化
 
 ```ts
-const currency = new SmartUnit(['', 'K', 'M', 'B', 'T'], {
-  baseDigit: 1000,
-  useDecimal: true,
-  fractionDigits: 2,
-});
-
-currency.format('12345678901234567890');  // => "12345678.90T"
-```
+const i18nMap = {
+  ms: 'ms',
+  s: 'seconds',
+  m: 'minutes',
+  h: 'hours',
+}
+const t = (unit: keyof typeof i18nMap) => i18nMap[unit]
 
-## 测试
+const timeI18n = new SmartUnit(['ms', 1000, 's', 60, 'm', 60, 'h'], {
+  separator: ' ',
+}).withConvert(t)
 
-运行测试套件：
-
-```bash
-npm test
+timeI18n.formatChain(90000) // 1minutes 30seconds
+timeI18n.formatChain(9000000) // 2hours 30minutes
 ```
 
-## TypeScript
+## 使用 TypeScript
 
-smart-unit 使用 TypeScript 编写，提供完整的类型安全。
+SmartUnit拥有完整的类型安全支持，适用于 TypeScript 项目。
 
 ```ts
-import SmartUnit from 'smart-unit';
-import type { Decimal } from 'decimal.js';
+import SmartUnit, { type GetUnitNames } from 'smart-unit'
 
-// 普通模式 - 返回 number
-const regular = new SmartUnit(['B', 'KB', 1024]);
-const num: number = regular.parse('1KB');
+const time = new SmartUnit(['ms', 1000, 's', 60, 'm', 60, 'h'])
+// 使用工具函数导出类型
+type TimeUnits = GetUnitNames<typeof time> // => type TimeUnits = "m" | "ms" | "s" | "h"
 
-// 高精度模式 - 返回 Decimal
-const precise = new SmartUnit(['B', 'KB', 1024], { useDecimal: true });
-const dec: Decimal = precise.parse('1KB');
+// t函数必须能接受所有TimeUnits单位，否则将导致类型错误
+const timeI18n = time.withConvert(t)
+// toBase的unit参数收到TimeUnits类型约束
+time.toBase(60, 'h')
 ```
 
 ## 贡献

package/dist/SmartUnit.d.ts

@@ -0,0 +1,60 @@
+import { SmartUnitBase } from './SmartUnitBase';
+import { type FormattedValue, type FractionDigits, type InputNumber, type SmartUnitOptions } from './utils';
+export declare class SmartUnit<U extends string = string> extends SmartUnitBase<U> {
+    constructor(units: (U | number)[], option?: SmartUnitOptions);
+    /**
+     * Gets the appropriate unit and adjusted value for the input number
+     *
+     * @param num - The input number to determine the unit for
+     * @param fractionDigits - Decimal precision configuration
+     * @returns The FormattedValue object containing the number, unit, and formatted number string
+     */
+    getUnit(num: InputNumber, fractionDigits?: FractionDigits): FormattedValue<U>;
+    /**
+     * Formats a number as a string with unit and optional decimal place configuration
+     *
+     * @param num - The input number to format
+     * @param fractionDigits - Decimal precision configuration (defaults to instance setting)
+     *   - If a number, defines fixed decimal places
+     *   - If a string in "min-max" format, defines a range of decimal places
+     *   - If omitted, uses the instance's default decimal configuration
+     * @returns The formatted string with number and unit (e.g. "1.50KB")
+     */
+    format(num: InputNumber, fractionDigits?: FractionDigits): string;
+    /**
+     * Gets the chain of units for the input number
+     * @param num - The input number to determine the chain for
+     * @returns An array of FormattedValue objects representing the chain of units
+     */
+    getChainUnit(num: InputNumber): FormattedValue<U>[];
+    /**
+     * Formats a number as a chain of units string
+     * @param num - The input number to format
+     * @returns The formatted chain string
+     */
+    formatChain(num: InputNumber, separator?: string): string;
+    /**
+     * Converts a value from the specified unit to the base unit
+     *
+     * @param num - The number to convert
+     * @param unit - The original unit of the number
+     * @returns The converted value in base unit
+     */
+    toBase(num: InputNumber, unit: U): number;
+    /**
+     * Parses a string with unit into a base unit numeric value
+     *
+     * @param str - Input string containing a number and unit
+     * @returns The value converted to base unit
+     */
+    parse(str: string): number;
+    /**
+     * Converts a value from the original unit to the optimal unit with optional decimal precision
+     *
+     * @param num - The number to convert
+     * @param unit - The original unit
+     * @param fractionDigits - Optional decimal places for formatting output
+     * @returns The converted number as a formatted string
+     */
+    fromUnitFormat(num: InputNumber, unit: U, fractionDigits?: FractionDigits): string;
+}

package/dist/SmartUnitBase.d.ts

@@ -0,0 +1,77 @@
+import type Decimal from 'decimal.js';
+import type { FormattedValue, FractionDigits, InputNumber, SmartUnitOptions } from './utils';
+export declare abstract class SmartUnitBase<U extends string = string, D extends boolean = false> {
+    readonly threshold: number;
+    readonly separator: string;
+    readonly fractionDigits?: FractionDigits;
+    readonly unitNames: U[];
+    readonly unitDigits: number[];
+    _accumulatedDigits?: number[];
+    /** Accumulated digits for unit conversion */
+    get accumulatedDigits(): number[];
+    _sortedUnitNames?: U[];
+    /** Sorted unit names by length for efficient lookup */
+    get sortedUnitNames(): U[];
+    convert?: (str: U) => string;
+    constructor(units: (U | number)[], option?: SmartUnitOptions);
+    withConvert(convert: (str: U) => string): this;
+    protected createAccumulatedDigits(): void;
+    protected createSortedUnitNames(): void;
+    /**
+     * Formats the decimal places of a number
+     *
+     * @param value - The value to format
+     * @param fractionDigits - Decimal precision configuration
+     * @returns The formatted string representation of the number
+     */
+    formatNumber(value: number | Decimal, fractionDigits?: FractionDigits): string;
+    abstract getUnit(num: InputNumber, fractionDigits?: FractionDigits): FormattedValue<U>;
+    protected _format(numStr: string, unit: U): string;
+    abstract format(num: InputNumber, fractionDigits?: FractionDigits): string;
+    /**
+     * Gets the chain of units for the input number
+     *
+     * @param num - The input number to determine the chain for
+     * @returns An array of FormattedValue objects representing the chain of units
+     */
+    abstract getChainUnit(num: InputNumber): FormattedValue<U>[];
+    protected _formatChain(chain: FormattedValue<U>[], separator?: string): string;
+    /**
+     * Formats a number as a chain of units string
+     * @param num - The input number to format
+     * @returns The formatted chain string
+     */
+    formatChain(num: InputNumber, separator?: string): string;
+    /**
+     * Converts a value from the specified unit to the base unit
+     *
+     * @param num - The number to convert
+     * @param unit - The original unit of the number
+     * @returns The converted value in base unit
+     */
+    abstract toBase(num: InputNumber, unit: U): D extends true ? Decimal : number;
+    /**
+     * Splits a string into its numeric part and unit
+     *
+     * @param str - Input string containing a number followed by a unit
+     * @returns An object containing the numeric value, unit, and Decimal instance
+     * @throws An error if no predefined unit is matched
+     */
+    splitUnit(str: string): FormattedValue<U>;
+    /**
+     * Parses a string with unit into a base unit numeric value
+     *
+     * @param str - Input string containing a number and unit
+     * @returns The value converted to base unit
+     */
+    abstract parse(str: string): D extends true ? Decimal : number;
+    /**
+     * Converts a value from the original unit to the optimal unit with optional decimal precision
+     *
+     * @param num - The number to convert
+     * @param unit - The original unit
+     * @param fractionDigits - Optional decimal places for formatting output
+     * @returns The converted number as a formatted string
+     */
+    abstract fromUnitFormat(num: InputNumber, unit: U, fractionDigits?: FractionDigits): string;
+}