a-calc 3.0.0-beta.20260105 → 3.0.0-beta.20260121

package/calc.d.ts

@@ -1,7 +1,7 @@
 import { U, StrRemoveSome, If_StrIncludes, Or, Equal } from "typescript-treasure";
 
 export type InjectDataFn<Expr> = <const Data>
-    ( fill_data: Data extends string | number | undefined | null ? never : Data ) =>
+    (fill_data: Data extends string | number | undefined | null ? never : Data) =>
     (
         If_HasNumFmt<Expr, Data> extends true ?
         number | GetWrapErr<Data>
@@ -11,7 +11,7 @@ export type InjectDataFn<Expr> = <const Data>
 
 
 export type InjectExprFn<Data> = <const Expr>
-    ( expr: Expr extends string | number ? Expr : never ) =>
+    (expr: Expr extends string | number ? Expr : never) =>
     (
         If_HasNumFmt<Expr, Data> extends true ?
         number | GetWrapErr<Data>
@@ -20,7 +20,7 @@ export type InjectExprFn<Data> = <const Expr>
     );
 
 
-type If_IncludesVar<T> = U.If_IncludeVar<StrRemoveSome<T, ["!n","!e","!u","!N","!E","!U"]>>;
+type If_IncludesVar<T> = U.If_IncludeVar<StrRemoveSome<T, ["!n", "!e", "!u", "!N", "!E", "!U"]>>;
 
 
 type If_NumOrStr<T> = T extends string | number ? true : false;
@@ -74,12 +74,20 @@ type CalcConfig<Fmt extends string, Err> =
         _unit: boolean,
         _fmt: Fmt,
         _memo: boolean,
-        _mode: "space" | "space-all" | "normal", // space 只会影响表达式部分 space_all 也会影响 fmt 部分
         [Prop: 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?: CalcConfig<Fmt, Err>) =>
+    (
+        If_StrIncludes<Fmt, ["!n"]> & If_StrIncludes<Expr, ["!n"]> extends true ?
+        number | Err
+        :
+        string | Err
+    );
+
+export type CalcSpace = <const Expr extends string | number, const Fmt extends string, const Err = never>
+    (expr: Expr, options?: CalcConfig<Fmt, Err>) =>
     (
         If_StrIncludes<Fmt, ["!n"]> & If_StrIncludes<Expr, ["!n"]> extends true ?
         number | Err
@@ -88,7 +96,7 @@ export type Calc = <const Expr extends string | number, const Fmt extends string
     );
 
 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<CalcConfig<Fmt, Err>>) =>
     (
         If_StrIncludes<Fmt, ["!n"]> & If_StrIncludes<Expr, ["!n"]> extends true ?
         number | Err
@@ -102,17 +110,21 @@ export type CalcSum = <const Expr extends string | number, const Fmt extends str
 export interface FmtOptions {
     _error?: any;
     _fmt?: string;
-    _volume_units?: string[];
-    _volume_step?: number;
-    _presets?: Record<string, any>;
-    _unit_to?: Record<string, any>;
-    _unit_from?: Record<string, any>;
-    _unit_default_to?: string | string[];
-    _unit_default_from?: string | string[];
-    _unit_position?: 'before' | 'after' | 'middle';
-    _unit_positions?: Record<string, 'before' | 'after' | 'middle'>;
-    _thousands_presets?: Record<string, any>;
+    /** 交易量单位数组（仅选项，临时覆盖） */
+    _vol_units?: string[];
+    /** 交易量阶梯值（仅选项，临时覆盖） */
+    _vol_step?: number | number[];
+    /** 交易量预设配置（仅选项） */
+    _vol?: Record<string, VolumePreset>;
+    _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>;
     [key: string]: any;
 }
 
@@ -128,16 +140,15 @@ export interface Fmt {
     ): If_StrIncludes<FmtStr, ["!n"]> extends true ? number | Err : string | Err;
 }
 
-export interface CalcWrap
-{
+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 | "-";
+        (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>>
-        ( expr: Expr, options: Options ): DirectReturn<Expr, Options>;
+        (expr: Expr, options: Options): DirectReturn<Expr, Options>;
 
     <const Fmt extends string, const Err, const Options extends CalcConfig<Fmt, Err>>
-        ( options: Options ): FuncReturn<Options>;
+        (options: Options): FuncReturn<Options>;
 }
 
 declare const calc_util: {
@@ -152,7 +163,7 @@ declare const calc_util: {
 };
 
 /**
- * 传入字符串算术式或数字返回计算的结果
+ * 传入字符串算术式或数字返回计算的结果（标准语法）
  * @param expr 一个字符串算术式或一个数字
  * @param options 一个配置或者用来填充算术式的数据源,或者两者的结合
  * @returns 返回进过计算和格式化之后的结果,结果可能是字符串或数字或自定义的错误类型
@@ -169,6 +180,24 @@ declare const calc_util: {
  */
 export const calc: Calc;
 
+/**
+ * 空格语法计算函数
+ * 使用空格分隔的语法，支持所有 3.x 新功能（千分位预设、格式化分组、范围限制等）
+ * @param expr 一个字符串算术式或一个数字（使用空格语法）
+ * @param options 一个配置或者用来填充算术式的数据源,或者两者的结合
+ * @returns 返回进过计算和格式化之后的结果,结果可能是字符串或数字或自定义的错误类型
+ *
+ * @example:
+ * ```typescript
+ * calc_space("a + b", {a: 1, b: 2}) // 3
+ * calc_space("1 + 2 * 3 | = 2") // "7.00"
+ * calc_space("100 | , = 2") // "100.00"
+ * calc_space("1000000 | @cn") // "1,000,000"（使用千分位预设）
+ * calc_space("100 | % = 2") // "100.00%"
+ * ```
+ */
+export const calc_space: CalcSpace;
+
 /**
  * 传入字符串算术式和数据源的数组进行计算并最终归集，这个方法类似 options_arr.reduce((memo, data) => calc("expr + memo", {expr, memo, _fill_data: data}), 0)
  * @param expr 一个字符串算术式或一个数字
@@ -383,6 +412,75 @@ export type ComputeMode = 'decimal' | 'bigint' | 'wasm';
  */
 export type AngleUnit = 'deg' | 'rad';
 
+/**
+ * 单位转换规则类型
+ */
+export type UnitConvertRule =
+    | number
+    | ((value: number, input_unit: string, output_unit: string) => number)
+    | {
+        mul?: number;
+        div?: number;
+        plus?: number;
+        minus?: number;
+        fn?: (value: number, input_unit: string, output_unit: string) => number;
+        _position?: 'before' | 'after' | 'middle';
+        _thousands?: string;
+        _vol?: string;
+    };
+
+/**
+ * 单位转换映射类型（输出单位为key）
+ */
+export type UnitConvertOut = Record<string, Record<string, UnitConvertRule> & {
+    _position?: 'before' | 'after' | 'middle';
+    _thousands?: string;
+    _vol?: string;
+}>;
+
+/**
+ * 单位转换映射类型（输入单位为key）
+ */
+export type UnitConvertIn = Record<string, Record<string, UnitConvertRule>>;
+
+/**
+ * 千分位预设配置类型
+ */
+export interface ThousandsPreset {
+    /** 千分位分隔符，默认 ',' */
+    sep?: string;
+    /** 小数点符号，默认 '.' */
+    point?: string;
+    /** 分组规则，默认 [3] */
+    grouping?: number[];
+    /** 最小触发位数，0 表示不限制 */
+    min_len?: number;
+    /** 是否对小数部分分组 */
+    point_group?: boolean;
+    /** 自定义格式化函数 */
+    fn?: (num_str: string, context: { int_part: string; dec_part: string | null; sign: string; options: any }) => string;
+}
+
+/**
+ * 交易量预设配置类型
+ */
+export type VolumePreset =
+    | string[]  // 简写形式：只有单位数组，step 默认 1000
+    | {         // 完整形式：包含 units 和 step
+        units: string[];
+        step?: number | number[];
+    }
+    | ((num_str: string, context: {  // 自定义函数形式
+        decimals: number;
+        options: any;
+        current_unit?: string;
+    }) => {
+        sign: string;
+        number: string;
+        unit: string;
+        formatted: string;
+    } | string);  // 可以返回对象或字符串
+
 /**
  * 全局配置项
  */
@@ -399,6 +497,37 @@ export interface CalcConfig {
     _debug_console?: boolean;
     /** 自定义函数映射 */
     _custom_functions?: Record<string, (...args: any[]) => any>;
+
+    // ==================== 交易量配置 ====================
+    /** 交易量预设配置（支持对象、数组简写、自定义函数） */
+    _vol?: Record<string, VolumePreset>;
+    /** 默认交易量预设名称 */
+    _vol_default?: string;
+
+    // ==================== 单位转换配置 ====================
+    /** 单位转换映射（输出单位为key） */
+    _unit_convert_out?: UnitConvertOut;
+    /** 单位转换映射（输入单位为key，内部会转换为 _unit_convert_out 格式） */
+    _unit_convert_in?: UnitConvertIn;
+    /** 默认输出单位 */
+    _unit_default_out?: string | string[];
+    /** 默认输入单位（当有多个输入单位时指定默认从哪个单位转换） */
+    _unit_default_in?: string | string[];
+    /** 默认单位位置: 'after' | 'before' | 'middle' */
+    _unit_default_position?: 'before' | 'after' | 'middle';
+
+    // ==================== 单位联动映射 ====================
+    /** 单位到位置的映射 */
+    _unit_position_map?: Record<string, 'before' | 'after' | 'middle'>;
+    /** 单位到千分位预设的映射 */
+    _unit_thousands_map?: Record<string, string>;
+    /** 单位到交易量预设的映射 */
+    _unit_vol_map?: Record<string, string>;
+
+    // ==================== 千分位配置 ====================
+    /** 千分位预设配置 */
+    _thousands?: Record<string, ThousandsPreset>;
+
     /** 其他自定义配置 */
     [key: string]: any;
 }
@@ -425,6 +554,18 @@ export function set_config(config: CalcConfig): void;
 export function get_config(): CalcConfig;
 export function get_config<K extends keyof CalcConfig>(key: K): CalcConfig[K];
 
+/**
+ * 重置全局配置到默认值
+ *
+ * @example
+ * reset_config()                           // 重置所有配置
+ * reset_config('_unit_convert_out')        // 重置单个配置
+ * 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;
+
 /**
  * 运算符方法类型（内部使用，通过 r* 函数访问）
  */