a-calc 3.0.0-beta.20260124.1 → 3.0.0-beta.20260124.3

package/calc.d.ts

@@ -67,18 +67,29 @@ type If_DirectReturn<Arg1, Arg2> =
         If_NumOrStr<Arg1> & Not<If_IncludesVar<Arg1>>
     >;
 
-type CalcConfig<Fmt extends string, Err> =
+/**
+ * calc/calc_space 运行时选项类型（可以包含数据和配置）
+ */
+type CalcRuntimeOptions<Fmt extends string, Err> =
     any[] | Partial<{
-        _error: Err,
-        _fill_data: any,
-        _unit: boolean,
-        _fmt: Fmt,
-        _memo: boolean,
-        [Prop: string]: any;
+        _error: Err;
+        _fmt: Fmt;
+        _unit: boolean;
+        _debug?: boolean;
+        _on_debug?: (info: any) => void;
+        _angle_unit?: 'deg' | 'rad';
+        _compact_units?: string[];
+        _compact_step?: number | number[];
+        _thousands?: Record<string, ThousandsPreset>;
+        /** 多路取值时视为空值的值数组（仅运行时选项） */
+        _empty_values?: any[];
+        /** 多路取值时自定义空值判断函数（仅运行时选项） */
+        _empty_check?: (value: any, path?: string) => boolean;
+        [key: string]: any;  // 允许任意数据字段
     }>;
 
 export type Calc = <const Expr extends string | number, const Fmt extends string, const Err = never>
-    (expr: Expr, options?: CalcConfig<Fmt, Err>) =>
+    (expr: Expr, options?: CalcRuntimeOptions<Fmt, Err>) =>
     (
         If_StrIncludes<Fmt, ["!n"]> & If_StrIncludes<Expr, ["!n"]> extends true ?
         number | Err
@@ -87,7 +98,7 @@ export type Calc = <const Expr extends string | number, const Fmt extends string
     );
 
 export type CalcSpace = <const Expr extends string | number, const Fmt extends string, const Err = never>
-    (expr: Expr, options?: CalcConfig<Fmt, Err>) =>
+    (expr: Expr, options?: CalcRuntimeOptions<Fmt, Err>) =>
     (
         If_StrIncludes<Fmt, ["!n"]> & If_StrIncludes<Expr, ["!n"]> extends true ?
         number | Err
@@ -96,7 +107,7 @@ export type CalcSpace = <const Expr extends string | number, const Fmt extends s
     );
 
 export type CalcSum = <const Expr extends string | number, const Fmt extends string, const Err = never>
-    (expr: Expr, options: Array<CalcConfig<Fmt, Err>>) =>
+    (expr: Expr, options: Array<CalcRuntimeOptions<Fmt, Err>>) =>
     (
         If_StrIncludes<Fmt, ["!n"]> & If_StrIncludes<Expr, ["!n"]> extends true ?
         number | Err
@@ -105,26 +116,30 @@ export type CalcSum = <const Expr extends string | number, const Fmt extends str
     );
 
 /**
- * fmt 格式化选项
+ * fmt 格式化选项（运行时选项，可以包含数据）
  */
 export interface FmtOptions {
     _error?: any;
     _fmt?: string;
-    /** 交易量单位数组（仅选项，临时覆盖） */
-    _vol_units?: string[];
-    /** 交易量阶梯值（仅选项，临时覆盖） */
-    _vol_step?: number | number[];
-    /** 交易量预设配置（仅选项） */
-    _vol?: Record<string, VolumePreset>;
+    /** 紧凑格式单位数组（仅选项，临时覆盖） */
+    _compact_units?: string[];
+    /** 紧凑格式阶梯值（仅选项，临时覆盖） */
+    _compact_step?: number | number[];
+    /** 紧凑格式预设配置（仅选项） */
+    _compact?: Record<string, CompactPreset>;
     _unit_convert_out?: Record<string, any>;
     _unit_convert_in?: Record<string, any>;
     _unit_default_out?: string | string[];
     _unit_default_in?: string | string[];
     _unit_default_position?: 'before' | 'after' | 'middle';
-    _unit_default_positions?: Record<string, 'before' | 'after' | 'middle'>;
-    _thousands?: Record<string, any>;
-    _unit_thousands?: Record<string, string>;
-    _unit_vol?: Record<string, string>;
+    _unit_position_map?: Record<string, 'before' | 'after' | 'middle'>;
+    _thousands?: Record<string, ThousandsPreset>;
+    _unit_thousands_map?: Record<string, string>;
+    _unit_compact_map?: Record<string, string>;
+    /** 多路取值时视为空值的值数组（仅运行时选项） */
+    _empty_values?: any[];
+    /** 多路取值时自定义空值判断函数（仅运行时选项） */
+    _empty_check?: (value: any, path?: string) => boolean;
     [key: string]: any;
 }
 
@@ -144,10 +159,10 @@ export interface CalcWrap {
     <const Expr extends string | number>
         (expr: Expr): If_IncludesVar<Expr> extends true ? FuncReturn<Expr> : If_StrIncludes<Expr, ["!n", "!N"]> extends true ? number | "-" : string | "-";
 
-    <const Expr extends string | number, const Fmt extends string, const Err, const Options extends CalcConfig<Fmt, Err>>
+    <const Expr extends string | number, const Fmt extends string, const Err, const Options extends CalcRuntimeOptions<Fmt, Err>>
         (expr: Expr, options: Options): DirectReturn<Expr, Options>;
 
-    <const Fmt extends string, const Err, const Options extends CalcConfig<Fmt, Err>>
+    <const Fmt extends string, const Err, const Options extends CalcRuntimeOptions<Fmt, Err>>
         (options: Options): FuncReturn<Options>;
 }
 
@@ -443,6 +458,18 @@ export type UnitConvertOut = Record<string, Record<string, UnitConvertRule> & {
  */
 export type UnitConvertIn = Record<string, Record<string, UnitConvertRule>>;
 
+/**
+ * 千分位预设名称（系统内置）
+ * - us: 美式/英式/国际标准 (1,234,567.89)
+ * - eu: 欧洲大陆格式 (1.234.567,89)
+ * - swiss: 瑞士格式 (1'234'567.89)
+ * - space: 空格分隔/ISO标准 (1 234 567.89)
+ * - fr: 法国格式 (1 234 567,89 - 使用不换行空格)
+ * - indian: 印度格式 (12,34,567.89)
+ * - wan: 万进制/东亚格式 (123,4567.89)
+ */
+export type ThousandsPresetName = 'us' | 'eu' | 'swiss' | 'space' | 'fr' | 'indian' | 'wan';
+
 /**
  * 千分位预设配置类型
  */
@@ -462,9 +489,9 @@ export interface ThousandsPreset {
 }
 
 /**
- * 交易量预设配置类型
+ * 紧凑格式预设配置类型
  */
-export type VolumePreset =
+export type CompactPreset =
     | string[]  // 简写形式：只有单位数组，step 默认 1000
     | {         // 完整形式：包含 units 和 step
         units: string[];
@@ -482,27 +509,35 @@ export type VolumePreset =
     } | string);  // 可以返回对象或字符串
 
 /**
- * 全局配置项
+ * 全局配置项（只能通过 set_config 设置）
  */
-export interface CalcConfig {
+export interface GlobalConfig {
     /** 计算模式: "decimal" | "bigint" | "wasm" */
     _compute_mode?: ComputeMode;
     /** 角度单位: "deg" (度) | "rad" (弧度)，默认 "deg" */
     _angle_unit?: AngleUnit;
     /** 除法精度（小数位数），默认 20 */
     _div_precision?: number;
-    /** 错误时的返回值 */
+    /** 错误时的返回值，默认 '-' */
     _error?: any;
     /** 是否启用调试模式控制台输出，默认 true */
     _debug_console?: boolean;
-    /** 自定义函数映射 */
-    _custom_functions?: Record<string, (...args: any[]) => any>;
+    /** 默认舍入模式 */
+    _default_round?: string;
+    /** 默认格式化字符串（全局配置） */
+    _fmt?: string;
+    /** 内置函数映射 */
+    _builtin_functions?: Record<string, (...args: any[]) => any>;
 
-    // ==================== 交易量配置 ====================
-    /** 交易量预设配置（支持对象、数组简写、自定义函数） */
-    _vol?: Record<string, VolumePreset>;
-    /** 默认交易量预设名称 */
-    _vol_default?: string;
+    // ==================== 紧凑格式配置 ====================
+    /** 紧凑格式预设配置（全局配置） */
+    _compact?: Record<string, CompactPreset>;
+    /** 默认紧凑格式预设名称 */
+    _compact_default?: string;
+
+    // ==================== 格式化分组配置 ====================
+    /** 格式化分组（全局配置） */
+    _fmt_groups?: Record<string, string>;
 
     // ==================== 单位转换配置 ====================
     /** 单位转换映射（输出单位为key） */
@@ -521,15 +556,24 @@ export interface CalcConfig {
     _unit_position_map?: Record<string, 'before' | 'after' | 'middle'>;
     /** 单位到千分位预设的映射 */
     _unit_thousands_map?: Record<string, string>;
-    /** 单位到交易量预设的映射 */
-    _unit_vol_map?: Record<string, string>;
+    /** 单位到紧凑格式预设的映射 */
+    _unit_compact_map?: Record<string, string>;
 
     // ==================== 千分位配置 ====================
     /** 千分位预设配置 */
     _thousands?: Record<string, ThousandsPreset>;
-
-    /** 其他自定义配置 */
-    [key: string]: any;
+    /** 默认千分位预设名称 */
+    _thousands_default?: string;
+
+    // ==================== 快捷语法配置 ====================
+    /** 快捷语法前缀（:xxx 等同于 _shortcut_prefix:xxx），默认 '!u' */
+    _shortcut_prefix?: string;
+
+    // ==================== 多路取值配置 ====================
+    /** 多路取值时视为空值的值数组（全局配置，运行时选项可覆盖） */
+    _empty_values?: any[];
+    /** 多路取值时自定义空值判断函数（全局配置，运行时选项可覆盖） */
+    _empty_check?: (value: any, path?: string) => boolean;
 }
 
 /**
@@ -541,7 +585,7 @@ export interface CalcConfig {
  * set_config({ _div_precision: 30 })       // 设置除法精度为 30 位
  * set_config({ _error: 0 })                // 错误时返回 0
  */
-export function set_config(config: CalcConfig): void;
+export function set_config(config: GlobalConfig): void;
 
 /**
  * 获取全局配置
@@ -551,8 +595,8 @@ export function set_config(config: CalcConfig): void;
  * get_config('_compute_mode')  // => 'decimal'
  * get_config()                 // => { _compute_mode: 'decimal', ... }
  */
-export function get_config(): CalcConfig;
-export function get_config<K extends keyof CalcConfig>(key: K): CalcConfig[K];
+export function get_config(): GlobalConfig;
+export function get_config<K extends keyof GlobalConfig>(key: K): GlobalConfig[K];
 
 /**
  * 重置全局配置到默认值
@@ -563,8 +607,8 @@ export function get_config<K extends keyof CalcConfig>(key: K): CalcConfig[K];
  * reset_config(['_unit_convert_out', '_unit_default_out'])  // 重置多个配置
  */
 export function reset_config(): void;
-export function reset_config(key: keyof CalcConfig): void;
-export function reset_config(keys: (keyof CalcConfig)[]): void;
+export function reset_config(key: keyof GlobalConfig): void;
+export function reset_config(keys: (keyof GlobalConfig)[]): void;
 
 /**
  * 运算符方法类型（内部使用，通过 r* 函数访问）