smart-unit 1.0.5 → 2.1.0

package/dist/src/SmartUnitBase.d.ts

@@ -0,0 +1,55 @@
+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[];
+    /** Unit conversion function */
+    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;
+    abstract getChainUnit(num: InputNumber): FormattedValue<U>[];
+    protected _formatChain(chain: FormattedValue<U>[], separator?: string): string;
+    formatChain(num: InputNumber, separator?: string): string;
+    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>;
+    /**
+     * 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
+     */
+    splitChainUnit(str: string, separator?: string): FormattedValue<U>[];
+    abstract parse(str: string): D extends true ? Decimal : number;
+    abstract parseChain(str: string): D extends true ? Decimal : number;
+    abstract fromUnitFormat(num: InputNumber, unit: U, fractionDigits?: FractionDigits): string;
+}

package/dist/src/SmartUnitPrecision.d.ts

@@ -0,0 +1,97 @@
+import { type Decimal } from 'decimal.js';
+import { SmartUnitBase } from './SmartUnitBase';
+import { type FormattedValue, type FractionDigits, type InputNumber, type SmartUnitOptions } from './utils';
+export type DecimalOptions = Decimal.Config;
+export type NumPrecision = InputNumber | string | bigint | Decimal;
+export interface FormattedValuePrecision<U extends string> extends FormattedValue<U> {
+    decimal: Decimal;
+}
+export interface SmartUnitPrecisionOptions extends SmartUnitOptions {
+    /**
+     * Decimal.js configuration options
+     * - Creates an isolated Decimal class for this SmartUnit instance only
+     * - Used to customize precision and other parameters
+     */
+    decimalOptions?: DecimalOptions;
+}
+export declare class SmartUnitPrecision<U extends string = string> extends SmartUnitBase<U, true> {
+    private DecimalClass;
+    constructor(units: (U | number)[], option?: SmartUnitPrecisionOptions);
+    /**
+     * Gets the appropriate unit and adjusted value for the input number
+     *
+     * @param num - The input NumPrecision to determine the unit for
+     * @param fractionDigits - Decimal precision configuration
+     * @returns The FormattedValue object containing the number, unit, and decimal instance
+     */
+    getUnit(num: NumPrecision): FormattedValuePrecision<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
+     * @returns The formatted string with number and unit
+     */
+    format(num: NumPrecision, 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: NumPrecision): FormattedValuePrecision<U>[];
+    /**
+     * Formats a number as a chain of units string
+     *
+     * @param num - The input number to format
+     * @returns The formatted chain string
+     */
+    formatChain(num: NumPrecision, 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: NumPrecision, unit: U): Decimal;
+    /**
+     * 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): FormattedValuePrecision<U>;
+    /**
+     * 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
+     */
+    splitChainUnit(str: string, separator?: string): FormattedValuePrecision<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
+     */
+    parse(str: string): Decimal;
+    /**
+     * Parses a string with chain units into a base unit numeric value
+     *
+     * @param str - Input string containing a number and unit
+     * @returns The value converted to base unit
+     */
+    parseChain(str: string): Decimal;
+    /**
+     * 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: NumPrecision, unit: U, fractionDigits?: FractionDigits): string;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,9 @@
+/*!
+ * smart-unit
+ * Copyright (c) [2026] [flycran]
+ * MIT License. See LICENSE for details.
+ */
+export * from './SmartUnit';
+export * from './utils';
+import { SmartUnit } from './SmartUnit';
+export default SmartUnit;

package/dist/src/precision.d.ts

@@ -0,0 +1,9 @@
+/*!
+ * smart-unit
+ * Copyright (c) [2026] [flycran]
+ * MIT License. See LICENSE for details.
+ */
+export * from './SmartUnitPrecision';
+export * from './utils';
+import { SmartUnitPrecision } from './SmartUnitPrecision';
+export default SmartUnitPrecision;

package/dist/src/utils.d.ts

@@ -0,0 +1,32 @@
+import type { SmartUnitBase } from 'SmartUnitBase';
+export type FractionDigits = number | `-${number}` | `${number}-` | `${number}-${number}` | undefined;
+export interface SmartUnitOptions {
+    /** Base digit for auto-generating unit conversions */
+    baseDigit?: number;
+    /**
+     * Threshold for unit switching
+     * The comparison value is multiplied by this threshold
+     */
+    threshold?: number;
+    /**
+     * Number of decimal places to preserve in the result
+     * Can be a fixed number or a range like "min-max"
+     */
+    fractionDigits?: FractionDigits;
+    /**
+     * The separator for chain formatting
+     * - Default is an empty string
+     */
+    separator?: string;
+}
+export interface FormattedValue<U extends string> {
+    /** The numeric value */
+    num: number;
+    /** The unit string */
+    unit: U;
+    /** The number string with decimal places applied */
+    numStr: string;
+}
+export type InputNumber = number;
+export type GetUnitNames<SU extends SmartUnitBase<any>> = SU extends SmartUnitBase<infer U> ? U : never;
+export declare const ERROR_NAN_INPUT = "Accepting NaN as an argument may be unintentional and could lead to invalid results.";

package/dist/utils-4mK2MBi1.js

@@ -0,0 +1,181 @@
+'use strict';
+
+class SmartUnitBase {
+    /** Accumulated digits for unit conversion */
+    get accumulatedDigits() {
+        if (!this._accumulatedDigits)
+            this.createAccumulatedDigits();
+        return this._accumulatedDigits;
+    }
+    /** Sorted unit names by length for efficient lookup */
+    get sortedUnitNames() {
+        if (!this._sortedUnitNames)
+            this.createSortedUnitNames();
+        return this._sortedUnitNames;
+    }
+    constructor(units, option = {}) {
+        this.unitNames = [];
+        this.unitDigits = [];
+        // Initialize
+        if (!units.length)
+            throw new Error('units is empty.');
+        this.threshold = option.threshold || 1;
+        this.fractionDigits = option.fractionDigits;
+        this.separator = option.separator || '';
+        if (option.baseDigit) {
+            for (let i = 0; i < units.length; i++) {
+                const name = units[i];
+                if (typeof name !== 'string')
+                    throw new Error(`The unit setting is incorrect; the element at index [${i}] should be of string type.`);
+            }
+            this.unitNames = units;
+            this.unitDigits = Array(units.length - 1).fill(option.baseDigit);
+        }
+        else {
+            for (let i = 1; i < units.length; i += 2) {
+                const digit = units[i];
+                if (typeof digit !== 'number')
+                    throw new Error(`The unit setting is incorrect; the element at index [${i}] should be of numeric type.`);
+                this.unitDigits.push(units[i]);
+                const name = units[i - 1];
+                if (typeof name !== 'string')
+                    throw new Error(`The unit setting is incorrect; the element at index [${i - 1}] should be of string type.`);
+                this.unitNames.push(name);
+            }
+            this.unitNames.push(units[units.length - 1]);
+        }
+    }
+    withConvert(convert) {
+        const su = Object.create(this);
+        su.convert = convert;
+        return su;
+    }
+    // 累积比例
+    createAccumulatedDigits() {
+        const accumulatedDigits = [];
+        this.unitDigits.forEach((digit, index) => {
+            if (index === 0) {
+                accumulatedDigits.push(digit);
+            }
+            else {
+                accumulatedDigits.push(accumulatedDigits[index - 1] * digit);
+            }
+        });
+        this._accumulatedDigits = accumulatedDigits;
+    }
+    // 长度排序后的单位名称
+    createSortedUnitNames() {
+        const sortedUnits = [...this.unitNames].sort((a, b) => b.length - a.length);
+        this._sortedUnitNames = sortedUnits;
+    }
+    // 格式化数字的小数位数
+    /**
+     * 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, fractionDigits = this.fractionDigits) {
+        if (typeof fractionDigits === 'number') {
+            return value.toFixed(fractionDigits);
+        }
+        else if (typeof fractionDigits === 'string') {
+            const [dp1, dp2] = fractionDigits.split('-');
+            const ndp = (value.toString().split('.')[1] || '').length;
+            const minDp = dp1 ? +dp1 : -Infinity;
+            const maxDp = dp2 ? +dp2 : Infinity;
+            if (ndp < minDp) {
+                return value.toFixed(minDp);
+            }
+            else if (ndp > maxDp) {
+                return value.toFixed(maxDp);
+            }
+            else {
+                return value.toString();
+            }
+        }
+        else {
+            return value.toString();
+        }
+    }
+    // format抽象方法
+    _format(numStr, unit) {
+        return `${numStr}${this.convert ? this.convert(unit) : unit}`;
+    }
+    _formatChain(chain, separator = this.separator) {
+        return chain.map(({ numStr, unit }) => this._format(numStr, unit)).join(separator);
+    }
+    // 将数字格式化为链式单位字符串
+    formatChain(num, separator = this.separator) {
+        const chain = this.getChainUnit(num);
+        return this._formatChain(chain, separator);
+    }
+    // 从给定字符串中分离出数字部分和单位
+    /**
+     * 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) {
+        const sortedUnits = this.sortedUnitNames;
+        for (const unit of sortedUnits) {
+            const matchUnit = this.convert ? this.convert(unit) : unit;
+            if (str.endsWith(matchUnit)) {
+                const numStr = str.slice(0, -matchUnit.length);
+                const num = +numStr;
+                if (Number.isNaN(num))
+                    throw new Error(`Invalid number: "${numStr}".`);
+                return {
+                    num,
+                    unit,
+                    numStr,
+                };
+            }
+        }
+        throw new Error(`Undefined unit: "${str}".`);
+    }
+    // 从给定链式单位字符串中分离出数字部分和单位
+    /**
+     * 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
+     */
+    splitChainUnit(str, separator = this.separator) {
+        const results = [];
+        const sortedUnits = this.sortedUnitNames;
+        const strLen = str.length;
+        let start = 0;
+        for (let i = 0; i < strLen; i++) {
+            for (const unit of sortedUnits) {
+                const matchUnit = this.convert ? this.convert(unit) : unit;
+                if (str.slice(i, i + matchUnit.length) === matchUnit) {
+                    const numStr = str.slice(start, i);
+                    const num = +numStr;
+                    if (Number.isNaN(num))
+                        throw new Error(`Invalid number: "${numStr}".`);
+                    results.push({
+                        num,
+                        unit,
+                        numStr,
+                    });
+                    i += matchUnit.length + separator.length;
+                    start = i;
+                    break;
+                }
+            }
+        }
+        if (results.length > 0)
+            return results;
+        throw new Error(`Undefined unit: "${str}".`);
+    }
+}
+
+const ERROR_NAN_INPUT = 'Accepting NaN as an argument may be unintentional and could lead to invalid results.';
+
+exports.ERROR_NAN_INPUT = ERROR_NAN_INPUT;
+exports.SmartUnitBase = SmartUnitBase;

package/dist/utils-biRhOw5Y.js

@@ -0,0 +1,178 @@
+class SmartUnitBase {
+    /** Accumulated digits for unit conversion */
+    get accumulatedDigits() {
+        if (!this._accumulatedDigits)
+            this.createAccumulatedDigits();
+        return this._accumulatedDigits;
+    }
+    /** Sorted unit names by length for efficient lookup */
+    get sortedUnitNames() {
+        if (!this._sortedUnitNames)
+            this.createSortedUnitNames();
+        return this._sortedUnitNames;
+    }
+    constructor(units, option = {}) {
+        this.unitNames = [];
+        this.unitDigits = [];
+        // Initialize
+        if (!units.length)
+            throw new Error('units is empty.');
+        this.threshold = option.threshold || 1;
+        this.fractionDigits = option.fractionDigits;
+        this.separator = option.separator || '';
+        if (option.baseDigit) {
+            for (let i = 0; i < units.length; i++) {
+                const name = units[i];
+                if (typeof name !== 'string')
+                    throw new Error(`The unit setting is incorrect; the element at index [${i}] should be of string type.`);
+            }
+            this.unitNames = units;
+            this.unitDigits = Array(units.length - 1).fill(option.baseDigit);
+        }
+        else {
+            for (let i = 1; i < units.length; i += 2) {
+                const digit = units[i];
+                if (typeof digit !== 'number')
+                    throw new Error(`The unit setting is incorrect; the element at index [${i}] should be of numeric type.`);
+                this.unitDigits.push(units[i]);
+                const name = units[i - 1];
+                if (typeof name !== 'string')
+                    throw new Error(`The unit setting is incorrect; the element at index [${i - 1}] should be of string type.`);
+                this.unitNames.push(name);
+            }
+            this.unitNames.push(units[units.length - 1]);
+        }
+    }
+    withConvert(convert) {
+        const su = Object.create(this);
+        su.convert = convert;
+        return su;
+    }
+    // 累积比例
+    createAccumulatedDigits() {
+        const accumulatedDigits = [];
+        this.unitDigits.forEach((digit, index) => {
+            if (index === 0) {
+                accumulatedDigits.push(digit);
+            }
+            else {
+                accumulatedDigits.push(accumulatedDigits[index - 1] * digit);
+            }
+        });
+        this._accumulatedDigits = accumulatedDigits;
+    }
+    // 长度排序后的单位名称
+    createSortedUnitNames() {
+        const sortedUnits = [...this.unitNames].sort((a, b) => b.length - a.length);
+        this._sortedUnitNames = sortedUnits;
+    }
+    // 格式化数字的小数位数
+    /**
+     * 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, fractionDigits = this.fractionDigits) {
+        if (typeof fractionDigits === 'number') {
+            return value.toFixed(fractionDigits);
+        }
+        else if (typeof fractionDigits === 'string') {
+            const [dp1, dp2] = fractionDigits.split('-');
+            const ndp = (value.toString().split('.')[1] || '').length;
+            const minDp = dp1 ? +dp1 : -Infinity;
+            const maxDp = dp2 ? +dp2 : Infinity;
+            if (ndp < minDp) {
+                return value.toFixed(minDp);
+            }
+            else if (ndp > maxDp) {
+                return value.toFixed(maxDp);
+            }
+            else {
+                return value.toString();
+            }
+        }
+        else {
+            return value.toString();
+        }
+    }
+    // format抽象方法
+    _format(numStr, unit) {
+        return `${numStr}${this.convert ? this.convert(unit) : unit}`;
+    }
+    _formatChain(chain, separator = this.separator) {
+        return chain.map(({ numStr, unit }) => this._format(numStr, unit)).join(separator);
+    }
+    // 将数字格式化为链式单位字符串
+    formatChain(num, separator = this.separator) {
+        const chain = this.getChainUnit(num);
+        return this._formatChain(chain, separator);
+    }
+    // 从给定字符串中分离出数字部分和单位
+    /**
+     * 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) {
+        const sortedUnits = this.sortedUnitNames;
+        for (const unit of sortedUnits) {
+            const matchUnit = this.convert ? this.convert(unit) : unit;
+            if (str.endsWith(matchUnit)) {
+                const numStr = str.slice(0, -matchUnit.length);
+                const num = +numStr;
+                if (Number.isNaN(num))
+                    throw new Error(`Invalid number: "${numStr}".`);
+                return {
+                    num,
+                    unit,
+                    numStr,
+                };
+            }
+        }
+        throw new Error(`Undefined unit: "${str}".`);
+    }
+    // 从给定链式单位字符串中分离出数字部分和单位
+    /**
+     * 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
+     */
+    splitChainUnit(str, separator = this.separator) {
+        const results = [];
+        const sortedUnits = this.sortedUnitNames;
+        const strLen = str.length;
+        let start = 0;
+        for (let i = 0; i < strLen; i++) {
+            for (const unit of sortedUnits) {
+                const matchUnit = this.convert ? this.convert(unit) : unit;
+                if (str.slice(i, i + matchUnit.length) === matchUnit) {
+                    const numStr = str.slice(start, i);
+                    const num = +numStr;
+                    if (Number.isNaN(num))
+                        throw new Error(`Invalid number: "${numStr}".`);
+                    results.push({
+                        num,
+                        unit,
+                        numStr,
+                    });
+                    i += matchUnit.length + separator.length;
+                    start = i;
+                    break;
+                }
+            }
+        }
+        if (results.length > 0)
+            return results;
+        throw new Error(`Undefined unit: "${str}".`);
+    }
+}
+
+const ERROR_NAN_INPUT = 'Accepting NaN as an argument may be unintentional and could lead to invalid results.';
+
+export { ERROR_NAN_INPUT as E, SmartUnitBase as S };

package/package.json

@@ -1,48 +1,59 @@
 {
   "name": "smart-unit",
-  "version": "1.0.5",
-  "description": "Elegant unit conversion utility with automatic unit selection and high-precision support",
-  "main": "dist/index.js",
-  "module": "dist/index.esm.js",
-  "exports": {
-    ".": {
-      "import": "./dist/index.esm.js",
-      "require": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    }
+  "type": "module",
+  "version": "2.1.0",
+  "author": "flycran",
+  "scripts": {
+    "build": "rollup -c",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:performance": "node scripts/src/performance.ts",
+    "format": "biome format --fix .",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
   },
-  "types": "dist/index.d.ts",
   "repository": {
     "type": "git",
     "url": "https://github.com/flycran/smart-unit.git"
   },
-  "homepage": "https://github.com/flycran/smart-unit#readme",
-  "bugs": {
-    "url": "https://github.com/flycran/smart-unit/issues"
-  },
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
   "devDependencies": {
     "@biomejs/biome": "2.4.7",
     "@rollup/plugin-commonjs": "^28.0.3",
     "@rollup/plugin-node-resolve": "^16.0.1",
-    "@rollup/plugin-typescript": "^12.1.2",
+    "@rollup/plugin-typescript": "^12.3.0",
     "rollup": "~4.30.1",
-    "rollup-plugin-terser": "^7.0.2",
-    "terser": "^5.39.0",
-    "ts-node": "^10.9.1",
-    "tslib": "^2.8.1",
     "typescript": "^5.8.3",
+    "vitepress": "^1.6.4",
     "vitest": "^4.1.0"
   },
+  "peerDependencies": {
+    "decimal.js": "^10.5.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./precision": {
+      "types": "./dist/precision.d.ts",
+      "import": "./dist/precision.mjs",
+      "require": "./dist/precision.cjs"
+    }
+  },
+  "bugs": {
+    "url": "https://github.com/flycran/smart-unit/issues"
+  },
+  "description": "Elegant unit conversion utility with automatic unit selection and high-precision support",
   "files": [
     "dist",
     "README.md",
     "README.zh-CN.md"
   ],
-  "scripts": {
-    "build": "rollup -c --configPlugin typescript",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
+  "homepage": "https://github.com/flycran/smart-unit#readme",
   "keywords": [
     "unit",
     "unit-conversion",
@@ -54,9 +65,6 @@
     "bigint",
     "typescript"
   ],
-  "author": "flycran",
   "license": "MIT",
-  "dependencies": {
-    "decimal.js": "^10.5.0"
-  }
-}
+  "types": "dist/index.d.ts"
+}