smart-unit 1.0.4 → 2.0.0

package/dist/precision.cjs

@@ -0,0 +1,195 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var DecimalConstructor = require('decimal.js');
+var utils = require('./utils-DqEXot5a.js');
+
+class SmartUnitPrecision extends utils.SmartUnitBase {
+    constructor(units, option = {}) {
+        super(units, option);
+        this.DecimalClass = DecimalConstructor;
+        if (option.decimalOptions) {
+            this.DecimalClass = DecimalConstructor.clone(option.decimalOptions);
+        }
+    }
+    // 根据输入数值获取单位和调整后的值
+    /**
+     * 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) {
+        if (Number.isNaN(num))
+            throw new Error(utils.ERROR_NAN_INPUT);
+        const unitDigitsLen = this.unitDigits.length;
+        const dn = new this.DecimalClass(typeof num === 'bigint' ? num.toString() : num);
+        const isNegative = dn.isNegative();
+        let absDn = isNegative ? dn.abs() : dn;
+        let i = 0;
+        while (i < unitDigitsLen) {
+            const digit = this.unitDigits[i];
+            if (absDn.lt(digit * this.threshold)) {
+                break;
+            }
+            absDn = absDn.dividedBy(digit);
+            i++;
+        }
+        const result = isNegative ? absDn.neg() : absDn;
+        const n = result.toNumber();
+        return {
+            num: n,
+            decimal: result,
+            unit: this.unitNames[i],
+            numStr: this.formatNumber(result, this.fractionDigits),
+        };
+    }
+    // 将数字转换为字符串表示形式，并可选择配置小数位数
+    /**
+     * 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, fractionDigits = this.fractionDigits) {
+        const { decimal, unit } = this.getUnit(num);
+        const formatted = this.formatNumber(decimal, fractionDigits);
+        return `${formatted}${this.convert ? this.convert(unit) : unit}`;
+    }
+    // 根据输入数值获取链式单位数组
+    /**
+     * 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) {
+        if (Number.isNaN(num))
+            throw new Error(utils.ERROR_NAN_INPUT);
+        const result = [];
+        if (num === 0) {
+            return [{ num: 0, unit: this.unitNames[0], numStr: '0', decimal: new this.DecimalClass(0) }];
+        }
+        const dn = new this.DecimalClass(typeof num === 'bigint' ? num.toString() : num);
+        const isNegative = dn.isNegative();
+        let absDn = isNegative ? dn.abs() : dn;
+        for (let i = this.accumulatedDigits.length - 1; i >= 0; i--) {
+            const accDigit = this.accumulatedDigits[i];
+            if (absDn.gte(accDigit)) {
+                const res = absDn.dividedToIntegerBy(accDigit);
+                const val = isNegative ? res.neg() : res;
+                result.push({
+                    num: val.toNumber(),
+                    decimal: new this.DecimalClass(val),
+                    unit: this.unitNames[i + 1],
+                    numStr: this.formatNumber(val, this.fractionDigits),
+                });
+                absDn = absDn.minus(new this.DecimalClass(val).times(accDigit));
+                if (absDn.isZero())
+                    break;
+            }
+        }
+        if (!absDn.isZero()) {
+            const val = isNegative ? absDn.neg() : absDn;
+            result.push({
+                num: val.toNumber(),
+                decimal: val,
+                unit: this.unitNames[0],
+                numStr: this.formatNumber(val, this.fractionDigits),
+            });
+        }
+        return result;
+    }
+    // 将数字格式化为链式单位字符串
+    /**
+     * Formats a number as a chain of units string
+     *
+     * @param num - The input number to format
+     * @returns The formatted chain string
+     */
+    formatChain(num, separator = this.separator) {
+        const chain = this.getChainUnit(num);
+        return chain
+            .map(({ numStr, unit }) => `${numStr}${this.convert ? this.convert(unit) : unit}`)
+            .join(separator);
+    }
+    // 将给定数值从指定单位转换为基本单位
+    /**
+     * 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, unit) {
+        if (Number.isNaN(num))
+            throw new Error(utils.ERROR_NAN_INPUT);
+        const unitDigitsLen = this.unitDigits.length;
+        let dn = new this.DecimalClass(typeof num === 'bigint' ? num.toString() : num);
+        for (let i = 0; i < unitDigitsLen; i++) {
+            const digit = this.unitDigits[i];
+            if (this.unitNames[i] === unit) {
+                return dn;
+            }
+            dn = dn.times(digit);
+        }
+        if (unit === this.unitNames.at(-1)) {
+            return dn;
+        }
+        throw new Error(`Undefined unit: "${unit}".`);
+    }
+    // 从给定字符串中分离出数字部分和单位
+    /**
+     * 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 { num, unit, numStr } = super.splitUnit(str);
+        return {
+            num,
+            decimal: new this.DecimalClass(numStr),
+            unit,
+            numStr,
+        };
+    }
+    // 将带单位的值转换为基础单位的数值
+    /**
+     * 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) {
+        const { decimal, unit } = this.splitUnit(str);
+        return this.toBase(decimal, unit);
+    }
+    // 将给定数值从原单位转换为最佳单位，并可指定小数精度
+    /**
+     * 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, unit, fractionDigits) {
+        const nnum = this.toBase(num, unit);
+        return this.format(nnum, fractionDigits);
+    }
+}
+
+/*!
+ * smart-unit
+ * Copyright (c) [2026] [flycran]
+ * MIT License. See LICENSE for details.
+ */
+
+exports.ERROR_NAN_INPUT = utils.ERROR_NAN_INPUT;
+exports.SmartUnitPrecision = SmartUnitPrecision;
+exports.default = SmartUnitPrecision;

package/dist/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/precision.mjs

@@ -0,0 +1,189 @@
+import DecimalConstructor from 'decimal.js';
+import { S as SmartUnitBase, E as ERROR_NAN_INPUT } from './utils-C1byK7Uk.js';
+
+class SmartUnitPrecision extends SmartUnitBase {
+    constructor(units, option = {}) {
+        super(units, option);
+        this.DecimalClass = DecimalConstructor;
+        if (option.decimalOptions) {
+            this.DecimalClass = DecimalConstructor.clone(option.decimalOptions);
+        }
+    }
+    // 根据输入数值获取单位和调整后的值
+    /**
+     * 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) {
+        if (Number.isNaN(num))
+            throw new Error(ERROR_NAN_INPUT);
+        const unitDigitsLen = this.unitDigits.length;
+        const dn = new this.DecimalClass(typeof num === 'bigint' ? num.toString() : num);
+        const isNegative = dn.isNegative();
+        let absDn = isNegative ? dn.abs() : dn;
+        let i = 0;
+        while (i < unitDigitsLen) {
+            const digit = this.unitDigits[i];
+            if (absDn.lt(digit * this.threshold)) {
+                break;
+            }
+            absDn = absDn.dividedBy(digit);
+            i++;
+        }
+        const result = isNegative ? absDn.neg() : absDn;
+        const n = result.toNumber();
+        return {
+            num: n,
+            decimal: result,
+            unit: this.unitNames[i],
+            numStr: this.formatNumber(result, this.fractionDigits),
+        };
+    }
+    // 将数字转换为字符串表示形式，并可选择配置小数位数
+    /**
+     * 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, fractionDigits = this.fractionDigits) {
+        const { decimal, unit } = this.getUnit(num);
+        const formatted = this.formatNumber(decimal, fractionDigits);
+        return `${formatted}${this.convert ? this.convert(unit) : unit}`;
+    }
+    // 根据输入数值获取链式单位数组
+    /**
+     * 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) {
+        if (Number.isNaN(num))
+            throw new Error(ERROR_NAN_INPUT);
+        const result = [];
+        if (num === 0) {
+            return [{ num: 0, unit: this.unitNames[0], numStr: '0', decimal: new this.DecimalClass(0) }];
+        }
+        const dn = new this.DecimalClass(typeof num === 'bigint' ? num.toString() : num);
+        const isNegative = dn.isNegative();
+        let absDn = isNegative ? dn.abs() : dn;
+        for (let i = this.accumulatedDigits.length - 1; i >= 0; i--) {
+            const accDigit = this.accumulatedDigits[i];
+            if (absDn.gte(accDigit)) {
+                const res = absDn.dividedToIntegerBy(accDigit);
+                const val = isNegative ? res.neg() : res;
+                result.push({
+                    num: val.toNumber(),
+                    decimal: new this.DecimalClass(val),
+                    unit: this.unitNames[i + 1],
+                    numStr: this.formatNumber(val, this.fractionDigits),
+                });
+                absDn = absDn.minus(new this.DecimalClass(val).times(accDigit));
+                if (absDn.isZero())
+                    break;
+            }
+        }
+        if (!absDn.isZero()) {
+            const val = isNegative ? absDn.neg() : absDn;
+            result.push({
+                num: val.toNumber(),
+                decimal: val,
+                unit: this.unitNames[0],
+                numStr: this.formatNumber(val, this.fractionDigits),
+            });
+        }
+        return result;
+    }
+    // 将数字格式化为链式单位字符串
+    /**
+     * Formats a number as a chain of units string
+     *
+     * @param num - The input number to format
+     * @returns The formatted chain string
+     */
+    formatChain(num, separator = this.separator) {
+        const chain = this.getChainUnit(num);
+        return chain
+            .map(({ numStr, unit }) => `${numStr}${this.convert ? this.convert(unit) : unit}`)
+            .join(separator);
+    }
+    // 将给定数值从指定单位转换为基本单位
+    /**
+     * 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, unit) {
+        if (Number.isNaN(num))
+            throw new Error(ERROR_NAN_INPUT);
+        const unitDigitsLen = this.unitDigits.length;
+        let dn = new this.DecimalClass(typeof num === 'bigint' ? num.toString() : num);
+        for (let i = 0; i < unitDigitsLen; i++) {
+            const digit = this.unitDigits[i];
+            if (this.unitNames[i] === unit) {
+                return dn;
+            }
+            dn = dn.times(digit);
+        }
+        if (unit === this.unitNames.at(-1)) {
+            return dn;
+        }
+        throw new Error(`Undefined unit: "${unit}".`);
+    }
+    // 从给定字符串中分离出数字部分和单位
+    /**
+     * 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 { num, unit, numStr } = super.splitUnit(str);
+        return {
+            num,
+            decimal: new this.DecimalClass(numStr),
+            unit,
+            numStr,
+        };
+    }
+    // 将带单位的值转换为基础单位的数值
+    /**
+     * 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) {
+        const { decimal, unit } = this.splitUnit(str);
+        return this.toBase(decimal, unit);
+    }
+    // 将给定数值从原单位转换为最佳单位，并可指定小数精度
+    /**
+     * 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, unit, fractionDigits) {
+        const nnum = this.toBase(num, unit);
+        return this.format(nnum, fractionDigits);
+    }
+}
+
+/*!
+ * smart-unit
+ * Copyright (c) [2026] [flycran]
+ * MIT License. See LICENSE for details.
+ */
+
+export { ERROR_NAN_INPUT, SmartUnitPrecision, SmartUnitPrecision as default };

package/dist/utils-C1byK7Uk.js

@@ -0,0 +1,146 @@
+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);
+    }
+    // 将数字格式化为链式单位字符串
+    /**
+     * Formats a number as a chain of units string
+     * @param num - The input number to format
+     * @returns The formatted chain string
+     */
+    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) {
+            if (str.endsWith(unit)) {
+                const numStr = str.slice(0, -unit.length);
+                const num = +numStr;
+                if (Number.isNaN(num))
+                    throw new Error(`Invalid number: "${numStr}".`);
+                return {
+                    num,
+                    unit,
+                    numStr,
+                };
+            }
+        }
+        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/dist/utils-DqEXot5a.js

@@ -0,0 +1,149 @@
+'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);
+    }
+    // 将数字格式化为链式单位字符串
+    /**
+     * Formats a number as a chain of units string
+     * @param num - The input number to format
+     * @returns The formatted chain string
+     */
+    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) {
+            if (str.endsWith(unit)) {
+                const numStr = str.slice(0, -unit.length);
+                const num = +numStr;
+                if (Number.isNaN(num))
+                    throw new Error(`Invalid number: "${numStr}".`);
+                return {
+                    num,
+                    unit,
+                    numStr,
+                };
+            }
+        }
+        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;