@planarcat/js-toolkit 1.3.1 → 1.5.0

package/README.md

@@ -70,7 +70,7 @@ debouncedFn();
 ### 数字格式化
 
 ```typescript
-import { toFormattedNumber } from '@planarcat/js-toolkit';
+import { toFormattedNumber, toFormattedNumberString } from '@planarcat/js-toolkit';
 
 // 基本使用
 console.log(toFormattedNumber(1234.5678));
@@ -96,6 +96,41 @@ console.log(
     ])
 );
 // 输出: [[1, 1.23], [45.67, [89.01, NaN]]]
+
+// 数字转格式化字符串
+console.log(toFormattedNumberString(1234.5678, { decimalPlaces: 2 }));
+// 输出: "1234.57"
+
+// 保留两位小数，不够时补0
+console.log(toFormattedNumberString(123.4, { decimalPlaces: 2 }));
+// 输出: "123.40"
+
+// 带前缀后缀
+console.log(toFormattedNumberString(1234.5678, { prefix: '$', suffix: ' USD' }));
+// 输出: "$1234.5678 USD"
+
+// 本地化格式
+console.log(toFormattedNumberString(1234567.89, { useLocalizedFormat: true }));
+// 输出: "1,234,567.89"
+
+// 自定义NaN和0显示
+console.log(toFormattedNumberString(null, { nanValue: 'N/A' }));
+// 输出: "N/A"
+console.log(toFormattedNumberString(0, { zeroValue: '-' }));
+// 输出: "-"
+
+// 预处理函数
+console.log(
+    toFormattedNumberString(0.1234, {
+        preProcessor: num => num * 100,
+        suffix: '%',
+    })
+);
+// 输出: "12.34%"
+
+// 处理数组
+console.log(toFormattedNumberString([123.456, '789.012'], { decimalPlaces: 2 }));
+// 输出: ["123.46", "789.01"]
 ```
 
 ## API 文档
@@ -196,6 +231,15 @@ npm run test:coverage
 
 ## 更新日志
 
+### v1.4.0
+
+- ✨ 优化数字格式化功能，无数字字符串返回 `0` 而不是 `NaN`
+- ✨ 改进 `toFormattedNumberString` 函数，无数字字符串直接返回 `zeroValue`
+- ✨ 为 `toFormattedNumberString` 函数的前缀后缀添加函数类型支持
+- ✨ 完善文档和测试用例
+- ✨ 优化深层数组处理逻辑
+- ✨ 修复 0 值、NaN 值和无数字字符串的前缀后缀处理问题
+
 ### v1.3.0
 
 - ✨ 添加数字格式化功能 `toFormattedNumber`

package/dist/index.d.ts

@@ -10,5 +10,6 @@ export type { DebounceOptions, DebouncedFunction } from "./types/function";
 export declare const VERSION = "__VERSION__";
 export declare const LIBRARY_NAME = "@planarcat/js-toolkit";
 export { default as toFormattedNumber } from "./object/toFormattedNumber";
-export type { ToFormattedNumberOptions } from "./types/object";
+export { default as toFormattedNumberString } from "./object/toFormattedNumberString";
+export type { ToFormattedNumberOptions, ToFormattedNumberStringOptions, } from "./types/object";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC1D,YAAY,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAGjE,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC1D,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAG3E,eAAO,MAAM,OAAO,gBAAgB,CAAC;AACrC,eAAO,MAAM,YAAY,0BAA0B,CAAC;AAGpD,OAAO,EAAE,OAAO,IAAI,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC1E,YAAY,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC1D,YAAY,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAGjE,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC1D,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAG3E,eAAO,MAAM,OAAO,gBAAgB,CAAC;AACrC,eAAO,MAAM,YAAY,0BAA0B,CAAC;AAGpD,OAAO,EAAE,OAAO,IAAI,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC1E,OAAO,EAAE,OAAO,IAAI,uBAAuB,EAAE,MAAM,kCAAkC,CAAC;AACtF,YAAY,EACV,wBAAwB,EACxB,8BAA8B,GAC/B,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -8,7 +8,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toFormattedNumber = exports.LIBRARY_NAME = exports.VERSION = exports.debounce = exports.formatDate = void 0;
+exports.toFormattedNumberString = exports.toFormattedNumber = exports.LIBRARY_NAME = exports.VERSION = exports.debounce = exports.formatDate = void 0;
 // 日期相关工具
 var formatDate_1 = require("./date/formatDate");
 Object.defineProperty(exports, "formatDate", { enumerable: true, get: function () { return __importDefault(formatDate_1).default; } });
@@ -21,6 +21,8 @@ exports.LIBRARY_NAME = "@planarcat/js-toolkit";
 // 对象相关工具
 var toFormattedNumber_1 = require("./object/toFormattedNumber");
 Object.defineProperty(exports, "toFormattedNumber", { enumerable: true, get: function () { return __importDefault(toFormattedNumber_1).default; } });
+var toFormattedNumberString_1 = require("./object/toFormattedNumberString");
+Object.defineProperty(exports, "toFormattedNumberString", { enumerable: true, get: function () { return __importDefault(toFormattedNumberString_1).default; } });
 // 工具函数（后续添加）
 // export { default as toNumber } from './number/toNumber';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;;;;AAEH,SAAS;AACT,gDAA0D;AAAjD,yHAAA,OAAO,OAAc;AAG9B,SAAS;AACT,gDAA0D;AAAjD,qHAAA,OAAO,OAAY;AAG5B,SAAS;AACI,QAAA,OAAO,GAAG,aAAa,CAAC,CAAC,QAAQ;AACjC,QAAA,YAAY,GAAG,uBAAuB,CAAC;AAEpD,SAAS;AACT,gEAA0E;AAAjE,uIAAA,OAAO,OAAqB;AAGrC,aAAa;AACb,2DAA2D"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;;;;AAEH,SAAS;AACT,gDAA0D;AAAjD,yHAAA,OAAO,OAAc;AAG9B,SAAS;AACT,gDAA0D;AAAjD,qHAAA,OAAO,OAAY;AAG5B,SAAS;AACI,QAAA,OAAO,GAAG,aAAa,CAAC,CAAC,QAAQ;AACjC,QAAA,YAAY,GAAG,uBAAuB,CAAC;AAEpD,SAAS;AACT,gEAA0E;AAAjE,uIAAA,OAAO,OAAqB;AACrC,4EAAsF;AAA7E,mJAAA,OAAO,OAA2B;AAM3C,aAAa;AACb,2DAA2D"}

package/dist/object/toFormattedNumber.d.ts

@@ -5,12 +5,12 @@
  * 对于字符串，会提取其中的数字部分进行转换
  * 支持深层数组递归处理
  *
- * @param object - 要格式化的对象，可以是任何类型
+ * @param object - 要格式化的目标
  * @param options - 格式化选项
  * @param options.decimalPlaces - 保留多少位小数，默认true（保留所有小数位）
  *                               true: 保留所有小数位，不额外处理
  *                               number: 保留指定小数位，四舍五入
- * @param options.nanDisplay - 当值为NaN时的显示，默认NaN
+ * @param options.nanValue - 当值为NaN时的显示，默认NaN
  *
  * @returns 格式化后的数字或数字数组
  *          - 如果输入是单个值，返回格式化后的数字
@@ -36,24 +36,26 @@
  * toFormattedNumber(undefined); // NaN
  * toFormattedNumber(Symbol('test')); // NaN
  * toFormattedNumber(() => {}); // NaN
+ * toFormattedNumber('abc'); // 0
+ * toFormattedNumber(''); // 0
  *
  * // 一维数组
  * toFormattedNumber([123.456, '456.789def']); // [123.456, 456.789]
  *
  * // 深层数组
  * toFormattedNumber([[1, '1', null], 'xxx', ['123a', ['123', '456ff']]]);
- * // 返回: [[1, 1, NaN], NaN, [123, [123, 456]]]
+ * // 返回: [[1, 1, NaN], 0, [123, [123, 456]]]
  *
  * // 保留指定小数位
  * toFormattedNumber(123.456, { decimalPlaces: 2 }); // 123.46
  * toFormattedNumber(123.456, { decimalPlaces: 0 }); // 123
  *
  * // 自定义NaN显示
- * toFormattedNumber(null, { nanDisplay: 0 }); // 0
- * toFormattedNumber('abc', { nanDisplay: -1 }); // -1
+ * toFormattedNumber(null, { nanValue: 0 }); // 0
+ * toFormattedNumber('abc', { nanValue: -1 }); // -1
  * ```
  */
-declare function toFormattedNumber(object: unknown[], options?: import('../types/object').ToFormattedNumberOptions): number[];
-declare function toFormattedNumber(object: unknown, options?: import('../types/object').ToFormattedNumberOptions): number | number[];
+declare function toFormattedNumber(object: unknown[], options?: import("../types/object").ToFormattedNumberOptions): number[];
+declare function toFormattedNumber(object: unknown, options?: import("../types/object").ToFormattedNumberOptions): number | number[];
 export default toFormattedNumber;
 //# sourceMappingURL=toFormattedNumber.d.ts.map

package/dist/object/toFormattedNumber.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toFormattedNumber.d.ts","sourceRoot":"","sources":["../../src/object/toFormattedNumber.ts"],"names":[],"mappings":"AA0CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,iBAAS,iBAAiB,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,OAAO,iBAAiB,EAAE,wBAAwB,GAAG,MAAM,EAAE,CAAC;AAEtH,iBAAS,iBAAiB,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,OAAO,iBAAiB,EAAE,wBAAwB,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC;AAgD7H,eAAe,iBAAiB,CAAC"}
+{"version":3,"file":"toFormattedNumber.d.ts","sourceRoot":"","sources":["../../src/object/toFormattedNumber.ts"],"names":[],"mappings":"AA0CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH,iBAAS,iBAAiB,CACxB,MAAM,EAAE,OAAO,EAAE,EACjB,OAAO,CAAC,EAAE,OAAO,iBAAiB,EAAE,wBAAwB,GAC3D,MAAM,EAAE,CAAC;AAEZ,iBAAS,iBAAiB,CACxB,MAAM,EAAE,OAAO,EACf,OAAO,CAAC,EAAE,OAAO,iBAAiB,EAAE,wBAAwB,GAC3D,MAAM,GAAG,MAAM,EAAE,CAAC;AAmDrB,eAAe,iBAAiB,CAAC"}

package/dist/object/toFormattedNumber.js

@@ -8,7 +8,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 function extractNumberFromString(str) {
     // 匹配数字体系：0~9，小数点，正负号，科学计数法
     const match = str.match(/[-+]?\d*\.?\d+(?:[eE][-+]?\d+)?/);
-    return match ? match[0] : '';
+    return match ? match[0] : "";
 }
 /**
  * 将单个值转换为数字
@@ -17,24 +17,24 @@ function extractNumberFromString(str) {
  */
 function convertToNumber(value) {
     switch (typeof value) {
-        case 'number':
+        case "number":
             return value;
-        case 'string': {
+        case "string": {
             const numStr = extractNumberFromString(value);
-            return numStr ? Number(numStr) : NaN;
+            return numStr ? Number(numStr) : 0;
         }
-        case 'boolean':
+        case "boolean":
             return value ? 1 : 0;
-        case 'function':
-        case 'symbol':
+        case "function":
+        case "symbol":
             return NaN;
-        case 'object':
+        case "object":
             if (value === null) {
                 return NaN;
             }
             // 其他对象类型返回NaN
             return NaN;
-        case 'undefined':
+        case "undefined":
             return NaN;
         default:
             return NaN;
@@ -43,7 +43,7 @@ function convertToNumber(value) {
 // 主函数实现
 function toFormattedNumber(object, options) {
     // 解构并设置默认值
-    const { decimalPlaces = true, nanDisplay = NaN } = options || {};
+    const { decimalPlaces = true, nanValue = NaN } = options || {};
     /**
      * 格式化单个数字
      * @param num - 要格式化的数字
@@ -52,7 +52,7 @@ function toFormattedNumber(object, options) {
     const formatSingleNumber = (num) => {
         // 处理NaN情况
         if (isNaN(num)) {
-            return nanDisplay;
+            return nanValue;
         }
         // 根据decimalPlaces选项处理小数位
         if (decimalPlaces === true) {

package/dist/object/toFormattedNumber.js.map

@@ -1 +1 @@
-{"version":3,"file":"toFormattedNumber.js","sourceRoot":"","sources":["../../src/object/toFormattedNumber.ts"],"names":[],"mappings":";;AAAA;;;;GAIG;AACH,SAAS,uBAAuB,CAAC,GAAW;IACxC,2BAA2B;IAC3B,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAC;IAC3D,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACjC,CAAC;AAED;;;;GAIG;AACH,SAAS,eAAe,CAAC,KAAc;IACnC,QAAQ,OAAO,KAAK,EAAE,CAAC;QACnB,KAAK,QAAQ;YACT,OAAO,KAAK,CAAC;QACjB,KAAK,QAAQ,CAAC,CAAC,CAAC;YACZ,MAAM,MAAM,GAAG,uBAAuB,CAAC,KAAK,CAAC,CAAC;YAC9C,OAAO,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;QACzC,CAAC;QACD,KAAK,SAAS;YACV,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACzB,KAAK,UAAU,CAAC;QAChB,KAAK,QAAQ;YACT,OAAO,GAAG,CAAC;QACf,KAAK,QAAQ;YACT,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACjB,OAAO,GAAG,CAAC;YACf,CAAC;YACD,cAAc;YACd,OAAO,GAAG,CAAC;QACf,KAAK,WAAW;YACZ,OAAO,GAAG,CAAC;QACf;YACI,OAAO,GAAG,CAAC;IACnB,CAAC;AACL,CAAC;AA6DD,QAAQ;AACR,SAAS,iBAAiB,CAAC,MAAe,EAAE,OAA4D;IACpG,WAAW;IACX,MAAM,EAAE,aAAa,GAAG,IAAI,EAAE,UAAU,GAAG,GAAG,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;IAEjE;;;;OAIG;IACH,MAAM,kBAAkB,GAAG,CAAC,GAAW,EAAU,EAAE;QAC/C,UAAU;QACV,IAAI,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;YACb,OAAO,UAAU,CAAC;QACtB,CAAC;QAED,yBAAyB;QACzB,IAAI,aAAa,KAAK,IAAI,EAAE,CAAC;YACzB,gBAAgB;YAChB,OAAO,GAAG,CAAC;QACf,CAAC;aAAM,CAAC;YACJ,eAAe;YACf,OAAO,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC;QAC9C,CAAC;IACL,CAAC,CAAC;IAEF;;;;OAIG;IACH,MAAM,YAAY,GAAG,CAAC,KAAc,EAAqB,EAAE;QACvD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACvB,WAAW;YACX,OAAO,KAAK,CAAC,GAAG,CAAC,YAAY,CAAa,CAAC;QAC/C,CAAC;aAAM,CAAC;YACJ,QAAQ;YACR,MAAM,GAAG,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;YACnC,QAAQ;YACR,OAAO,kBAAkB,CAAC,GAAG,CAAC,CAAC;QACnC,CAAC;IACL,CAAC,CAAC;IAEF,QAAQ;IACR,OAAO,YAAY,CAAC,MAAM,CAAC,CAAC;AAChC,CAAC;AAED,kBAAe,iBAAiB,CAAC"}
+{"version":3,"file":"toFormattedNumber.js","sourceRoot":"","sources":["../../src/object/toFormattedNumber.ts"],"names":[],"mappings":";;AAAA;;;;GAIG;AACH,SAAS,uBAAuB,CAAC,GAAW;IAC1C,2BAA2B;IAC3B,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAC;IAC3D,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC/B,CAAC;AAED;;;;GAIG;AACH,SAAS,eAAe,CAAC,KAAc;IACrC,QAAQ,OAAO,KAAK,EAAE,CAAC;QACrB,KAAK,QAAQ;YACX,OAAO,KAAK,CAAC;QACf,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,MAAM,MAAM,GAAG,uBAAuB,CAAC,KAAK,CAAC,CAAC;YAC9C,OAAO,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACrC,CAAC;QACD,KAAK,SAAS;YACZ,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACvB,KAAK,UAAU,CAAC;QAChB,KAAK,QAAQ;YACX,OAAO,GAAG,CAAC;QACb,KAAK,QAAQ;YACX,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACnB,OAAO,GAAG,CAAC;YACb,CAAC;YACD,cAAc;YACd,OAAO,GAAG,CAAC;QACb,KAAK,WAAW;YACd,OAAO,GAAG,CAAC;QACb;YACE,OAAO,GAAG,CAAC;IACf,CAAC;AACH,CAAC;AAqED,QAAQ;AACR,SAAS,iBAAiB,CACxB,MAAe,EACf,OAA4D;IAE5D,WAAW;IACX,MAAM,EAAE,aAAa,GAAG,IAAI,EAAE,QAAQ,GAAG,GAAG,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;IAE/D;;;;OAIG;IACH,MAAM,kBAAkB,GAAG,CAAC,GAAW,EAAU,EAAE;QACjD,UAAU;QACV,IAAI,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;YACf,OAAO,QAAQ,CAAC;QAClB,CAAC;QAED,yBAAyB;QACzB,IAAI,aAAa,KAAK,IAAI,EAAE,CAAC;YAC3B,gBAAgB;YAChB,OAAO,GAAG,CAAC;QACb,CAAC;aAAM,CAAC;YACN,eAAe;YACf,OAAO,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC,CAAC;IAEF;;;;OAIG;IACH,MAAM,YAAY,GAAG,CAAC,KAAc,EAAqB,EAAE;QACzD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,WAAW;YACX,OAAO,KAAK,CAAC,GAAG,CAAC,YAAY,CAAa,CAAC;QAC7C,CAAC;aAAM,CAAC;YACN,QAAQ;YACR,MAAM,GAAG,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;YACnC,QAAQ;YACR,OAAO,kBAAkB,CAAC,GAAG,CAAC,CAAC;QACjC,CAAC;IACH,CAAC,CAAC;IAEF,QAAQ;IACR,OAAO,YAAY,CAAC,MAAM,CAAC,CAAC;AAC9B,CAAC;AAED,kBAAe,iBAAiB,CAAC"}

package/dist/object/toFormattedNumberString.d.ts

@@ -0,0 +1,4 @@
+declare function toFormattedNumberString(object: unknown[], options?: import('../types/object').ToFormattedNumberStringOptions): string[];
+declare function toFormattedNumberString(object: unknown, options?: import('../types/object').ToFormattedNumberStringOptions): string | string[];
+export default toFormattedNumberString;
+//# sourceMappingURL=toFormattedNumberString.d.ts.map

package/dist/object/toFormattedNumberString.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toFormattedNumberString.d.ts","sourceRoot":"","sources":["../../src/object/toFormattedNumberString.ts"],"names":[],"mappings":"AAuEA,iBAAS,uBAAuB,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,OAAO,iBAAiB,EAAE,8BAA8B,GAAG,MAAM,EAAE,CAAC;AAElI,iBAAS,uBAAuB,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,OAAO,iBAAiB,EAAE,8BAA8B,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC;AAyHzI,eAAe,uBAAuB,CAAC"}

package/dist/object/toFormattedNumberString.js

@@ -0,0 +1,187 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * 将任意对象转化为格式化的数字字符串
+ *
+ * 该函数先使用toFormattedNumber将对象转化为数字，再对数字进行字符串格式化
+ * 支持多种输入类型，包括数字、字符串、布尔值、null、undefined、数组等
+ * 支持深层数组递归处理
+ *
+ * @param object - 要格式化的对象，可以是任何类型
+ * @param options - 格式化选项
+ * @param options.decimalPlaces - 保留多少位小数，默认true（保留所有小数位）
+ *                               true: 保留所有小数位，不额外处理
+ *                               number: 保留指定小数位，不够时补0
+ * @param options.nanValue - 当值为NaN时的显示，默认'NaN'
+ * @param options.zeroValue - 当值为0时的显示，默认'0'
+ * @param options.useLocalizedFormat - 是否使用本地化格式，默认false
+ * @param options.preProcessor - 预处理函数，在数字转换后、字符串格式化前应用
+ * @param options.prefix - 前缀，可以是字符串或函数，默认''
+ *                          如果是函数，会接收格式化前的数字作为参数，返回字符串作为前缀
+ * @param options.suffix - 后缀，可以是字符串或函数，默认''
+ *                          如果是函数，会接收格式化前的数字作为参数，返回字符串作为后缀
+ *
+ * @returns 格式化后的数字字符串或字符串数组
+ *          - 如果输入是单个值，返回格式化后的字符串
+ *          - 如果输入是数组，返回格式化后的字符串数组
+ *          - 支持深层数组递归处理
+ *
+ * @example
+ * ```typescript
+ * // 单个数字值
+ * toFormattedNumberString(123.456); // "123.456"
+ *
+ * // 保留两位小数，不够时补0
+ * toFormattedNumberString(123.4, { decimalPlaces: 2 }); // "123.40"
+ *
+ * // 带前缀后缀
+ * toFormattedNumberString(123.456, { prefix: '$', suffix: ' USD' }); // "$123.456 USD"
+ *
+ * // 本地化格式
+ * toFormattedNumberString(1234567.89, { useLocalizedFormat: true }); // "1,234,567.89"
+ *
+ * // 自定义NaN和0显示
+ * toFormattedNumberString(null, { nanValue: 'N/A' }); // "N/A"
+ * toFormattedNumberString(0, { zeroValue: '-' }); // "-"
+ *
+ * // 预处理函数
+ * toFormattedNumberString(0.1234, {
+ *   preProcessor: (num) => num * 100,
+ *   suffix: '%'
+ * }); // "12.34%"
+ *
+ * // 函数类型前缀
+ * toFormattedNumberString(123.456, {
+ *   prefix: (num) => `$${Math.floor(num)}`
+ * }); // "$123123.456"
+ *
+ * // 函数类型后缀
+ * toFormattedNumberString(123.456, {
+ *   suffix: (num) => `/${num.toFixed(0)}`
+ * }); // "123.456/123"
+ *
+ * // 处理数组
+ * toFormattedNumberString([123.456, '789.012'], { decimalPlaces: 2 }); // ["123.46", "789.01"]
+ *
+ * // 处理深层数组
+ * toFormattedNumberString([[1, '1.23'], ['45.67', [89.01, 'abc']]], { decimalPlaces: 2 });
+ * // 返回: [["1.00", "1.23"], ["45.67", ["89.01", "NaN"]]]
+ * ```
+ */
+const toFormattedNumber_1 = __importDefault(require("./toFormattedNumber"));
+// 主函数实现
+function toFormattedNumberString(object, options) {
+    // 解构并设置默认值
+    const { decimalPlaces = true, nanValue = 'NaN', zeroValue = '0', useLocalizedFormat = false, preProcessor, prefix = '', suffix = '' } = options || {};
+    /**
+     * 处理前缀或后缀，可以是字符串或函数
+     * @param prefixOrSuffix - 前缀或后缀，可以是字符串或函数
+     * @param num - 要传递给函数的数字
+     * @returns 处理后的前缀或后缀字符串
+     */
+    const processPrefixSuffix = (prefixOrSuffix, num) => {
+        if (typeof prefixOrSuffix === 'function') {
+            return prefixOrSuffix(num);
+        }
+        return prefixOrSuffix;
+    };
+    /**
+     * 添加前缀和后缀
+     * @param str - 要添加前缀后缀的字符串
+     * @param num - 要传递给前缀后缀函数的数字
+     * @returns 添加了前缀后缀的字符串
+     */
+    const addPrefixSuffix = (str, num) => {
+        const processedPrefix = processPrefixSuffix(prefix, num);
+        const processedSuffix = processPrefixSuffix(suffix, num);
+        return `${processedPrefix}${str}${processedSuffix}`;
+    };
+    /**
+     * 将单个数字转换为格式化字符串
+     * @param num - 要转换的数字
+     * @returns 格式化后的字符串
+     */
+    const convertNumberToString = (num) => {
+        // 处理0情况
+        if (num === 0) {
+            return addPrefixSuffix(zeroValue, num);
+        }
+        // 应用预处理函数
+        const processedNum = preProcessor ? preProcessor(num) : num;
+        // 格式化数字为字符串
+        let strNum;
+        if (useLocalizedFormat) {
+            // 使用本地化格式
+            if (decimalPlaces === true) {
+                // 保留所有小数位
+                strNum = processedNum.toLocaleString();
+            }
+            else {
+                // 保留指定小数位，不够时补0
+                strNum = processedNum.toLocaleString(undefined, {
+                    minimumFractionDigits: decimalPlaces,
+                    maximumFractionDigits: decimalPlaces,
+                });
+            }
+        }
+        else {
+            // 使用非本地化格式
+            if (decimalPlaces === true) {
+                // 保留所有小数位
+                strNum = processedNum.toString();
+            }
+            else {
+                // 保留指定小数位，不够时补0
+                strNum = processedNum.toFixed(decimalPlaces);
+            }
+        }
+        // 添加前缀和后缀
+        return addPrefixSuffix(strNum, processedNum);
+    };
+    /**
+     * 检查字符串是否包含数字
+     * @param str - 要检查的字符串
+     * @returns 是否包含数字
+     */
+    const hasNumbers = (str) => {
+        return /\d/.test(str);
+    };
+    /**
+     * 递归处理值，转换为格式化字符串
+     * @param value - 要处理的值
+     * @returns 格式化后的字符串或字符串数组
+     */
+    const processValue = (value) => {
+        if (Array.isArray(value)) {
+            // 递归处理数组
+            return value.map(processValue);
+        }
+        else {
+            // 检查是否为无数字的字符串
+            if (typeof value === 'string' && !hasNumbers(value)) {
+                // 无数字的字符串返回0
+                return addPrefixSuffix(zeroValue, 0);
+            }
+            // 对于其他类型，首先将输入转换为数字
+            // 注意：toFormattedNumber对于单个值会返回number类型
+            const num = (0, toFormattedNumber_1.default)(value, {
+                decimalPlaces,
+                nanValue: NaN,
+            });
+            // 检查是否为NaN
+            if (isNaN(num)) {
+                // 其他NaN情况，使用nanValue
+                return addPrefixSuffix(nanValue, num);
+            }
+            // 正常数字转换
+            return convertNumberToString(num);
+        }
+    };
+    // 处理输入值
+    return processValue(object);
+}
+exports.default = toFormattedNumberString;
+//# sourceMappingURL=toFormattedNumberString.js.map

package/dist/object/toFormattedNumberString.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toFormattedNumberString.js","sourceRoot":"","sources":["../../src/object/toFormattedNumberString.ts"],"names":[],"mappings":"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"}

package/dist/types/object.d.ts

@@ -17,6 +17,41 @@ export interface ToFormattedNumberOptions extends CommonFormatOptions {
      * 当值为NaN时的显示，
      * 默认NaN。
      */
-    nanDisplay?: number;
+    nanValue?: number;
+}
+/**
+ * toFormattedNumberString 函数的选项接口
+ */
+export interface ToFormattedNumberStringOptions extends CommonFormatOptions {
+    /**
+     * 当值为NaN时的显示，
+     * 默认'NaN'。
+     */
+    nanValue?: string;
+    /**
+     * 当值为0时的显示，
+     * 默认'0'。
+     */
+    zeroValue?: string;
+    /**
+     * 是否显示本地化，
+     * 默认false。
+     */
+    useLocalizedFormat?: boolean;
+    /**
+     * 预处理函数，在对象被处理为数字后调用，
+     * 默认无。
+     */
+    preProcessor?: (num: number) => number;
+    /**
+     * 前缀，可以是字符串或函数，
+     * 默认''。
+     */
+    prefix?: string | ((value: number) => string);
+    /**
+     * 后缀，可以是字符串或函数，
+     * 默认''。
+     */
+    suffix?: string | ((value: number) => string);
 }
 //# sourceMappingURL=object.d.ts.map

package/dist/types/object.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"object.d.ts","sourceRoot":"","sources":["../../src/types/object.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAChC;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,wBAAyB,SAAQ,mBAAmB;IACjE;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB"}
+{"version":3,"file":"object.d.ts","sourceRoot":"","sources":["../../src/types/object.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAChC;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,wBAAyB,SAAQ,mBAAmB;IACjE;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,8BAA+B,SAAQ,mBAAmB;IACvE;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;IACvC;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC;IAC9C;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC;CACjD"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@planarcat/js-toolkit",
-    "version": "1.3.1",
+    "version": "1.5.0",
     "description": "一个自用的带学习性质的（目前）现代化的 JavaScript/TypeScript 实用工具库，提供类型安全、高性能的常用函数，包括对象转换、日期处理、函数优化等开发常用工具。",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",