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

package/calc.d.ts

@@ -96,6 +96,38 @@ export type CalcSum = <const Expr extends string | number, const Fmt extends str
         string | Err
     );
 
+/**
+ * fmt 格式化选项
+ */
+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>;
+    _unit_thousands?: Record<string, string>;
+    [key: string]: any;
+}
+
+/**
+ * fmt 函数类型
+ * 直接格式化数字，跳过表达式解析
+ */
+export interface Fmt {
+    <const FmtStr extends string | undefined = undefined, const Err = never>(
+        value: number | string,
+        format_str?: FmtStr,
+        options?: FmtOptions & { _error?: Err }
+    ): If_StrIncludes<FmtStr, ["!n"]> extends true ? number | Err : string | Err;
+}
+
 export interface CalcWrap
 {
     <const Expr extends string | number>
@@ -150,12 +182,33 @@ export const calc: Calc;
  */
 export const calc_sum: CalcSum;
 /**
- *  calc方法的别名.传入字符串算术式或数字返回计算的结果
- * @param expr 一个字符串算术式或一个数字
- * @param options 一个配置或者用来填充算术式的数据源,或者两者的结合
- * @returns 返回进过计算和格式化之后的结果,结果可能是字符串或数字或自定义的错误类型
+ * 专用格式化函数，用于对数字进行格式化处理
+ * 相比 calc，它跳过表达式解析，性能更好
+ *
+ * 支持多种调用方式：
+ * 1. 新 API: fmt(100, '=2') - 直接格式化数字，性能最好
+ * 2. 旧 API: fmt('100 | =2') - calc 风格（向后兼容）
+ * 3. 旧 API: fmt(100, { _fmt: '=2' }) - 对象选项风格（向后兼容）
+ *
+ * @param value 要格式化的数字，或包含 | 的 calc 风格表达式
+ * @param format_str 格式化字符串，或选项对象（旧 API 兼容）
+ * @param options 可选配置项
+ * @returns 返回格式化后的结果
+ *
+ * @example:
+ * ```typescript
+ * // 新 API（推荐）
+ * fmt(100, '=2')           // '100.00'
+ * fmt(1234567, ',')        // '1,234,567'
+ * fmt(0.1234, '%=2')       // '12.34%'
+ *
+ * // 旧 API（向后兼容）
+ * fmt('100 | =2')          // '100.00'
+ * fmt('num | ,', { num: 1234567 })  // '1,234,567'
+ * fmt(100, { _fmt: '=2' }) // '100.00'
+ * ```
  */
-export const fmt: Calc;
+export const fmt: Fmt;
 /**
  * calc方法的包装版本,除了支持calc所有的功能还额外提供了更强大的类型推导和更灵活的编写方式
  * @param expr 一个字符串算术式或一个数字
@@ -175,89 +228,333 @@ declare const version: string;
 
 export const parse_thousands: (str: string) => string;
 
+// ==================== 原始运算函数类型 ====================
+
+type NumOrStr = number | string;
+type TypeArg = "number" | "string";
+
 /**
- * 传入两个数字或数字字符串进行相加并返回结果,可以指定第三个参数控制返回数字还是数字字符串
- * @param a 一个数字或数字字符串
- * @param b 另一个数字或数字字符串
- * @param type 输出数字还是字符串
- * @returns 计算得到的结果
+ * 二元运算函数类型（支持多参数）
+ * - 默认返回 number
+ * - 最后一个参数为 "string" 时返回 string
+ * - 最后一个参数为 "number" 时返回 number
  */
-export const plus: <const T extends "number" | "string" = "number">(a: number|string, b: number|string, type?: T) => T extends "number" ? number : string;
+interface BinaryOp {
+    // 无参数
+    (): number;
+    // 单参数
+    (a: NumOrStr): number;
+    (a: NumOrStr, type: "string"): string;
+    (a: NumOrStr, type: "number"): number;
+    // 双参数（兼容旧版）
+    (a: NumOrStr, b: NumOrStr): number;
+    (a: NumOrStr, b: NumOrStr, type: "string"): string;
+    (a: NumOrStr, b: NumOrStr, type: "number"): number;
+    // 三参数
+    (a: NumOrStr, b: NumOrStr, c: NumOrStr): number;
+    (a: NumOrStr, b: NumOrStr, c: NumOrStr, type: "string"): string;
+    (a: NumOrStr, b: NumOrStr, c: NumOrStr, type: "number"): number;
+    // 四参数
+    (a: NumOrStr, b: NumOrStr, c: NumOrStr, d: NumOrStr): number;
+    (a: NumOrStr, b: NumOrStr, c: NumOrStr, d: NumOrStr, type: "string"): string;
+    (a: NumOrStr, b: NumOrStr, c: NumOrStr, d: NumOrStr, type: "number"): number;
+    // 更多参数（fallback）
+    (...args: NumOrStr[]): number | string;
+}
+
 /**
- * 传入两个数字或数字字符串进行相减并返回结果,可以指定第三个参数控制返回数字还是数字字符串
- * @param a 一个数字或数字字符串
- * @param b 另一个数字或数字字符串
- * @param type 输出数字还是字符串
- * @returns 计算得到的结果
+ * 一元运算函数类型
  */
-export const sub: <const T extends "number" | "string" = "number">(a: number|string, b: number|string, type?: T) => T extends "number" ? number : string;
+interface UnaryOp {
+    (value: NumOrStr): number;
+    (value: NumOrStr, type: "string"): string;
+    (value: NumOrStr, type: "number"): number;
+}
+
 /**
- * 传入两个数字或数字字符串进行相乘并返回结果,可以指定第三个参数控制返回数字还是数字字符串
- * @param a 一个数字或数字字符串
- * @param b 另一个数字或数字字符串
- * @param type 输出数字还是字符串
- * @returns 计算得到的结果
+ * 加法 - 支持多参数
+ * @example
+ * add(1, 2)           // => 3 (number)
+ * add(1, 2, 3, 4)     // => 10 (number)
+ * add(1, 2, "string") // => "3" (string)
  */
-export const mul: <const T extends "number" | "string" = "number">(a: number|string, b: number|string, type?: T) => T extends "number" ? number : string;
+export const add: BinaryOp;
+
 /**
- * 传入两个数字或数字字符串进行相除并返回结果,可以指定第三个参数控制返回数字还是数字字符串
- * @param a 一个数字或数字字符串
- * @param b 另一个数字或数字字符串
- * @param type 输出数字还是字符串
- * @returns 计算得到的结果
+ * 减法 - 支持多参数
+ * @example
+ * sub(10, 3)           // => 7 (number)
+ * sub(10, 3, 2)        // => 5 (number)
+ * sub(10, 3, "string") // => "7" (string)
  */
-export const div: <const T extends "number" | "string" = "number">(a: number|string, b: number|string, type?: T) => T extends "number" ? number : string;
+export const sub: BinaryOp;
+
 /**
- * 传入两个数字或数字字符串进行整除并返回结果,可以指定第三个参数控制返回数字还是数字字符串
- * @param a 一个数字或数字字符串
- * @param b 另一个数字或数字字符串
- * @param type 输出数字还是字符串
- * @returns 计算得到的结果
+ * 乘法 - 支持多参数
+ * @example
+ * mul(2, 3)            // => 6 (number)
+ * mul(2, 3, 4)         // => 24 (number)
+ * mul(2, 3, "string")  // => "6" (string)
  */
-export const idiv: <const T extends "number" | "string" = "number">(a: number|string, b: number|string, type?: T) => T extends "number" ? number : string;
+export const mul: BinaryOp;
+
 /**
- * 传入两个数字或数字字符串进行幂运算并返回结果,可以指定第三个参数控制返回数字还是数字字符串
- * @param a 一个数字或数字字符串
- * @param b 另一个数字或数字字符串
- * @param type 输出数字还是字符串
- * @returns 计算得到的结果
+ * 除法 - 支持多参数
+ * @example
+ * div(100, 2)          // => 50 (number)
+ * div(100, 2, 5)       // => 10 (number)
+ * div(10, 0)           // throws Error or returns _error
  */
-export const pow: <const T extends "number" | "string" = "number">(a: number|string, b: number|string, type?: T) => T extends "number" ? number : string;
+export const div: BinaryOp;
+
 /**
- * 传入两个数字或数字字符串进行取模并返回结果,可以指定第三个参数控制返回数字还是数字字符串
- * @param a 一个数字或数字字符串
- * @param b 另一个数字或数字字符串
- * @param type 输出数字还是字符串
- * @returns 计算得到的结果
+ * 取模 - 支持多参数
+ * @example
+ * mod(10, 3)           // => 1 (number)
+ * mod(10, 3, "string") // => "1" (string)
  */
-export const mod: <const T extends "number" | "string" = "number">(a: number|string, b: number|string, type?: T) => T extends "number" ? number : string;
+export const mod: BinaryOp;
 
 /**
- * calc方法的精简版本,去除了对单位计算的支持但是这个方法性能更好一些,该方法永远不会报错,在计算出错的时候返回 -
- * @param expr 一个字符串计算式或数字,如果是计算式那么内部的所有单元都需要使用一个空格严格分割
- * @param fmt_expr 一个用于描述如何格式化计算结果的字符串表达式
- * @param data 用于填充算术式中变量的数据源可以是对象也可以是对象数组
- * @param err_value 计算错误时返回的结果,模式是 -
- * @returns string | number | Err
+ * 幂运算 - 支持多参数（右结合）
+ * @example
+ * pow(2, 3)            // => 8 (number)
+ * pow(2, 3, 2)         // => 512 (number) = 2^(3^2)
  */
-export const calc_lite: <const T extends string | null | undefined, const Err = "-">
-    (calc_expr: string | number, fmt_expr?: T, data?: any, err_value?: Err) =>
-    (
-        Or<Equal<T, null> | Equal<T, undefined>> extends true ?
-        ( string | Err )
-        :
-        (
-            If_StrIncludes<T, ["!n"]> extends true ?
-            number | Err
-            :
-            string | Err
-        )
-    )
+export const pow: BinaryOp;
+
 /**
- * 较为原始的计算方法,使用中缀表达式的顺序来传入参数
- * @param value1 计算数1
- * @param op "+" | "-" | "*" | "/" | "%" | "**" | "//"
- * @param value2 计算数2
- * @returns 计算结果
+ * 整除 - 支持多参数
+ * @example
+ * idiv(10, 3)          // => 3 (number)
+ * idiv(100, 7, 2)      // => 7 (number)
  */
-export const calc_mini: (value1: number | string, op: "+" | "-" | "*" | "/" | "%" | "**" | "//", value2: number | string) => string
+export const idiv: BinaryOp;
+
+/**
+ * 绝对值
+ * @example
+ * abs(-5)              // => 5 (number)
+ * abs(-5, "string")    // => "5" (string)
+ */
+export const abs: UnaryOp;
+
+/**
+ * 取负
+ * @example
+ * neg(5)               // => -5 (number)
+ * neg(-5, "string")    // => "5" (string)
+ */
+export const neg: UnaryOp;
+
+/**
+ * 平方根
+ * @example
+ * sqrt(16)             // => 4 (number)
+ * sqrt(2, "string")    // => "1.4142135623730950488" (string)
+ */
+export const sqrt: UnaryOp;
+
+/**
+ * 自然对数
+ * @example
+ * ln(Math.E)           // => 1 (number)
+ * ln(10, "string")     // => "2.302585..." (string)
+ */
+export const ln: UnaryOp;
+
+/**
+ * e 的 x 次方
+ * @example
+ * exp(1)               // => 2.718281828... (number)
+ * exp(0, "string")     // => "1" (string)
+ */
+export const exp: UnaryOp;
+
+// ==================== 计算模式 ====================
+
+/**
+ * 计算模式类型
+ */
+export type ComputeMode = 'decimal' | 'bigint' | 'wasm';
+
+/**
+ * 角度单位类型
+ */
+export type AngleUnit = 'deg' | 'rad';
+
+/**
+ * 全局配置项
+ */
+export interface CalcConfig {
+    /** 计算模式: "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>;
+    /** 其他自定义配置 */
+    [key: string]: any;
+}
+
+/**
+ * 设置全局配置
+ * @param config 配置对象
+ * @example
+ * set_config({ _compute_mode: 'bigint' })  // 切换到 BigInt 模式
+ * set_config({ _angle_unit: 'rad' })       // 使用弧度制
+ * set_config({ _div_precision: 30 })       // 设置除法精度为 30 位
+ * set_config({ _error: 0 })                // 错误时返回 0
+ */
+export function set_config(config: CalcConfig): void;
+
+/**
+ * 获取全局配置
+ * @param key 配置项名称，不传则返回全部配置
+ * @returns 配置值或全部配置对象
+ * @example
+ * 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];
+
+/**
+ * 运算符方法类型（内部使用，通过 r* 函数访问）
+ */
+export interface Ops {
+    // 基础运算
+    add: (a: string, b: string) => string;
+    sub: (a: string, b: string) => string;
+    mul: (a: string, b: string) => string;
+    div: (a: string, b: string) => string;
+    mod: (a: string, b: string) => string;
+    pow: (a: string, b: string) => string;
+    idiv: (a: string, b: string) => string;
+    // 一元运算
+    abs: (a: string) => string;
+    neg: (a: string) => string;
+    sqrt: (a: string) => string;
+    cbrt: (a: string) => string;
+    // 指数对数
+    exp: (a: string) => string;
+    ln: (a: string) => string;
+    log: (a: string, base: string) => string;
+    log2: (a: string) => string;
+    log10: (a: string) => string;
+    // 三角函数
+    sin: (a: string) => string;
+    cos: (a: string) => string;
+    tan: (a: string) => string;
+    asin: (a: string) => string;
+    acos: (a: string) => string;
+    atan: (a: string) => string;
+    // 双曲函数
+    sinh: (a: string) => string;
+    cosh: (a: string) => string;
+    tanh: (a: string) => string;
+    asinh: (a: string) => string;
+    acosh: (a: string) => string;
+    atanh: (a: string) => string;
+    // 取整
+    floor: (a: string) => string;
+    ceil: (a: string) => string;
+    trunc: (a: string) => string;
+    round: (a: string) => string;
+    // 比较
+    max: (a: string, b: string) => string;
+    min: (a: string, b: string) => string;
+    compare: (a: string, b: string) => number;
+    eq: (a: string, b: string) => boolean;
+    lt: (a: string, b: string) => boolean;
+    gt: (a: string, b: string) => boolean;
+    lte: (a: string, b: string) => boolean;
+    gte: (a: string, b: string) => boolean;
+}
+
+/**
+ * 加载 WASM 模块（异步）
+ * @returns Promise，加载完成后 resolve
+ */
+export function load_wasm(): Promise<any>;
+
+/**
+ * 检查 WASM 模块是否已加载
+ * @returns 是否已加载
+ */
+export function is_wasm_loaded(): boolean;
+
+/**
+ * WASM 表达式计算
+ * 直接传入复杂表达式字符串，内部完成解析和计算
+ * @param expr 表达式字符串
+ * @returns 计算结果字符串
+ * @example
+ * wcalc("1 + 2 * 3")           // => "7"
+ * wcalc("sqrt(16) + pow(2, 3)") // => "12"
+ */
+export function wcalc(expr: string): string;
+
+// ==================== r 前缀原始运算函数 ====================
+// 这些函数直接调用底层计算模式，字符串进字符串出，会跟随 _compute_mode 配置变化
+// 切换计算模式请使用: set_config({ _compute_mode: 'bigint' })
+
+// 基础运算
+export function radd(a: string, b: string): string;
+export function rsub(a: string, b: string): string;
+export function rmul(a: string, b: string): string;
+export function rdiv(a: string, b: string): string;
+export function rmod(a: string, b: string): string;
+export function rpow(a: string, b: string): string;
+export function ridiv(a: string, b: string): string;
+
+// 一元运算
+export function rabs(a: string): string;
+export function rneg(a: string): string;
+export function rsqrt(a: string): string;
+export function rcbrt(a: string): string;
+
+// 指数对数
+export function rexp(a: string): string;
+export function rln(a: string): string;
+export function rlog(a: string, base: string): string;
+export function rlog2(a: string): string;
+export function rlog10(a: string): string;
+
+// 三角函数
+export function rsin(a: string): string;
+export function rcos(a: string): string;
+export function rtan(a: string): string;
+export function rasin(a: string): string;
+export function racos(a: string): string;
+export function ratan(a: string): string;
+
+// 双曲函数
+export function rsinh(a: string): string;
+export function rcosh(a: string): string;
+export function rtanh(a: string): string;
+export function rasinh(a: string): string;
+export function racosh(a: string): string;
+export function ratanh(a: string): string;
+
+// 取整
+export function rfloor(a: string): string;
+export function rceil(a: string): string;
+export function rtrunc(a: string): string;
+export function rround(a: string): string;
+
+// 比较
+export function rmax(a: string, b: string): string;
+export function rmin(a: string, b: string): string;
+export function rcompare(a: string, b: string): number;
+export function req(a: string, b: string): boolean;
+export function rlt(a: string, b: string): boolean;
+export function rgt(a: string, b: string): boolean;
+export function rlte(a: string, b: string): boolean;
+export function rgte(a: string, b: string): boolean;