a-calc/calc.d.ts

A very powerful and easy-to-use number precision calculation and formatting library.

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) =>
    (
        If_HasNumFmt<Expr, Data> extends true ?
        number | GetWrapErr<Data>
        :
        string | GetWrapErr<Data>
    );


export type InjectExprFn<Data> = <const Expr>
    (expr: Expr extends string | number ? Expr : never) =>
    (
        If_HasNumFmt<Expr, Data> extends true ?
        number | GetWrapErr<Data>
        :
        string | GetWrapErr<Data>
    );


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;
type If_FillData<T> = T extends string | number | undefined | null ? false : true;
type Not<T> = T extends true ? false : true;

type GetWrapErr<T> = T extends { _error: infer I; } ? I : "-";
type GetFmt<T> = T extends { _fmt: infer I; } ? I : never;

type If_HasNumFmt<Expr, Data> =
    Or<
        If_StrIncludes<Expr, ["!n"]> | If_StrIncludes<GetFmt<Data>, ["!n"]>
    >;


type DirectReturn<Expr, Data> =
    If_HasNumFmt<Expr, Data> extends true ?
    (
        number | GetWrapErr<Data>
    )
    :
    (
        string | GetWrapErr<Data>
    );


type FuncReturn<Arg1> =
    If_IncludesVar<Arg1> extends true ?
    (
        InjectDataFn<Arg1>
    )
    :
    (
        If_FillData<Arg1> extends true ?
        InjectExprFn<Arg1>
        :
        never
    );

type If_DirectReturn<Arg1, Arg2> =
    Or<
        If_NumOrStr<Arg1> & If_FillData<Arg2>
        |
        If_NumOrStr<Arg1> & Not<If_IncludesVar<Arg1>>
    >;

/**
 * calc/calc_space 运行时选项类型（可以包含数据和配置）
 */
type CalcRuntimeOptions<Fmt extends string, Err> =
    any[] | Partial<{
        _error: Err;
        _fmt: Fmt;
        _unit: boolean;
        _debug?: boolean;
        _on_debug?: (info: any) => void;
        _angle_unit?: 'deg' | 'rad';
        _compact_symbols?: 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?: CalcRuntimeOptions<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?: CalcRuntimeOptions<Fmt, Err>) =>
    (
        If_StrIncludes<Fmt, ["!n"]> & If_StrIncludes<Expr, ["!n"]> extends true ?
        number | Err
        :
        string | Err
    );

export type CalcSum = <const Expr extends string | number, const Fmt extends string, const Err = never>
    (expr: Expr, options: Array<CalcRuntimeOptions<Fmt, Err>>) =>
    (
        If_StrIncludes<Fmt, ["!n"]> & If_StrIncludes<Expr, ["!n"]> extends true ?
        number | Err
        :
        string | Err
    );

/**
 * fmt 格式化选项（运行时选项）
 * 注意：单位转换相关配置（_unit_convert_out 等）只能通过 set_config 全局设置
 */
export interface FmtOptions {
    _error?: any;
    _fmt?: string;
    /** 紧凑格式符号数组（临时覆盖） */
    _compact_symbols?: string[];
    /** 紧凑格式阶梯值（临时覆盖） */
    _compact_step?: number | number[];
    /** 千分位预设配置 */
    _thousands?: Record<string, ThousandsPreset>;
    /** 多路取值时视为空值的值数组 */
    _empty_values?: any[];
    /** 多路取值时自定义空值判断函数 */
    _empty_check?: (value: any, path?: string) => boolean;
    [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>
        (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 CalcRuntimeOptions<Fmt, Err>>
        (expr: Expr, options: Options): DirectReturn<Expr, Options>;

    <const Fmt extends string, const Err, const Options extends CalcRuntimeOptions<Fmt, Err>>
        (options: Options): FuncReturn<Options>;
}

/**
 * 传入字符串算术式或数字返回计算的结果（标准语法）
 * @param expr 一个字符串算术式或一个数字
 * @param options 一个配置或者用来填充算术式的数据源,或者两者的结合
 * @returns 返回进过计算和格式化之后的结果,结果可能是字符串或数字或自定义的错误类型
 *
 * @example:
 * ```typescript
 * calc("a + b", {a: 1, b: 2}) // 3
 * calc("1.00") // 1
 * calc("1.00 | =3") // 1.000
 * calc("a + b | =2", {a: 0.1, b: 0.2}) // 0.30
 * calc("a++(b", {_error: null}) // null
 * calc("1% + 2%", {_unit: true}) // 3%
 * ```
 */
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 一个字符串算术式或一个数字
 * @param options_arr 数据源的集合
 * @returns 返回进过计算和格式化并归集之后的结果,结果可能是字符串或数字或自定义的错误类型
 *
 * @example:
 * ```typescript
 * calc_sum("a + 1", [{a: 1}, {a: 2}]) // 5
 * ```
 */
export const calc_sum: CalcSum;

/**
 * 计算数组中每个元素的表达式值并求平均值
 * @param expr 一个字符串算术式，可包含格式化指令
 * @param options_arr 数据源的集合
 * @returns 返回平均值结果
 *
 * @example:
 * ```typescript
 * calc_avg("score", [{score: 80}, {score: 90}, {score: 100}]) // '90'
 * calc_avg("score | =2", [{score: 80}, {score: 90}]) // '85.00'
 * ```
 */
export const calc_avg: CalcSum;

/**
 * 计算数组中每个元素的表达式值并返回最大值
 * @param expr 一个字符串算术式，可包含格式化指令
 * @param options_arr 数据源的集合
 * @returns 返回最大值结果
 *
 * @example:
 * ```typescript
 * calc_max("price", [{price: 10}, {price: 30}, {price: 20}]) // '30'
 * calc_max("price * qty | =2", [{price: 10, qty: 2}, {price: 5, qty: 3}]) // '20.00'
 * ```
 */
export const calc_max: CalcSum;

/**
 * 计算数组中每个元素的表达式值并返回最小值
 * @param expr 一个字符串算术式，可包含格式化指令
 * @param options_arr 数据源的集合
 * @returns 返回最小值结果
 *
 * @example:
 * ```typescript
 * calc_min("price", [{price: 10}, {price: 30}, {price: 20}]) // '10'
 * calc_min("stock | =0", [{stock: 50}, {stock: 10}, {stock: 30}]) // '10'
 * ```
 */
export const calc_min: CalcSum;

/**
 * 统计数组中表达式结果为真值（非零）的数量
 * @param expr 一个字符串算术式，可包含格式化指令
 * @param options_arr 数据源的集合
 * @returns 返回满足条件的数量
 *
 * @example:
 * ```typescript
 * calc_count("stock > 0", [{stock: 10}, {stock: 0}, {stock: 5}]) // '2'
 * calc_count("active", [{active: 1}, {active: 0}, {active: 1}]) // '2'
 * ```
 */
export const calc_count: CalcSum;

/**
 * 专用格式化函数，用于对数字进行格式化处理
 * 相比 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: Fmt;
/**
 * calc方法的包装版本,除了支持calc所有的功能还额外提供了更强大的类型推导和更灵活的编写方式
 * @param expr 一个字符串算术式或一个数字
 * @param options 一个配置或者用来填充算术式的数据源,或者两者的结合
 * @returns 返回进过计算和格式化之后的结果,结果可能是字符串或数字或自定义的错误类型
 *
 * @example:
 * ```typescript
 * // 先传入表达式还是先注入数据源都是可以的
 * calc_wrap("a + b")({a: 1, b: 2}) // 3
 * calc_wrap("a + b",{a: 1, b: 2}) // 3
 * calc_wrap({a: 0.1, b: 0.2})("a + b | =2") // 0.30
 * ```
 */
export const calc_wrap: CalcWrap;

/**
 * 当前库版本号
 */
export const version: string;

/**
 * 工具函数集合
 */
export const calc_util: {
    /**
     * 检查当前库是否有更新版本
     */
    check_update(): void;
    /**
     * 打印当前库的版本
     */
    print_version(): void;
};

export const parse_thousands: (str: string) => string;

// ==================== 原始运算函数类型 ====================

type NumOrStr = number | string;
type TypeArg = "number" | "string";

/**
 * 二元运算函数类型（支持多参数）
 * - 默认返回 number
 * - 最后一个参数为 "string" 时返回 string
 * - 最后一个参数为 "number" 时返回 number
 */
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;
}

/**
 * 一元运算函数类型
 */
interface UnaryOp {
    (value: NumOrStr): number;
    (value: NumOrStr, type: "string"): string;
    (value: NumOrStr, type: "number"): number;
}

/**
 * 加法 - 支持多参数
 * @example
 * add(1, 2)           // => 3 (number)
 * add(1, 2, 3, 4)     // => 10 (number)
 * add(1, 2, "string") // => "3" (string)
 */
export const add: BinaryOp;

/**
 * 减法 - 支持多参数
 * @example
 * sub(10, 3)           // => 7 (number)
 * sub(10, 3, 2)        // => 5 (number)
 * sub(10, 3, "string") // => "7" (string)
 */
export const sub: BinaryOp;

/**
 * 乘法 - 支持多参数
 * @example
 * mul(2, 3)            // => 6 (number)
 * mul(2, 3, 4)         // => 24 (number)
 * mul(2, 3, "string")  // => "6" (string)
 */
export const mul: BinaryOp;

/**
 * 除法 - 支持多参数
 * @example
 * div(100, 2)          // => 50 (number)
 * div(100, 2, 5)       // => 10 (number)
 * div(10, 0)           // throws Error or returns _error
 */
export const div: BinaryOp;

/**
 * 取模 - 支持多参数
 * @example
 * mod(10, 3)           // => 1 (number)
 * mod(10, 3, "string") // => "1" (string)
 */
export const mod: BinaryOp;

/**
 * 幂运算 - 支持多参数（右结合）
 * @example
 * pow(2, 3)            // => 8 (number)
 * pow(2, 3, 2)         // => 512 (number) = 2^(3^2)
 */
export const pow: BinaryOp;

/**
 * 整除 - 支持多参数
 * @example
 * idiv(10, 3)          // => 3 (number)
 * idiv(100, 7, 2)      // => 7 (number)
 */
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;

// ==================== 链式计算 API ====================

/**
 * 链式计算返回值类型
 * 可以直接调用获取结果，也可以继续链式调用
 */
export interface ChainValue {
    /** 获取结果，可选传入格式化字符串 */
    (format?: string): string;
    /** 链式加法 */
    add(...nums: (NumOrStr | ChainValue)[]): ChainValue;
    /** 链式减法 */
    sub(...nums: (NumOrStr | ChainValue)[]): ChainValue;
    /** 链式乘法 */
    mul(...nums: (NumOrStr | ChainValue)[]): ChainValue;
    /** 链式除法 */
    div(...nums: (NumOrStr | ChainValue)[]): ChainValue;
    /** 链式取模 */
    mod(...nums: (NumOrStr | ChainValue)[]): ChainValue;
    /** 链式幂运算 */
    pow(...nums: (NumOrStr | ChainValue)[]): ChainValue;
    /** 链式整除 */
    idiv(...nums: (NumOrStr | ChainValue)[]): ChainValue;
}

/**
 * 链式加法起始
 * @example
 * cadd(1, 2, 3)()           // => "6"
 * cadd(1, 2).mul(3)()       // => "9"
 * cadd(100).sub(50)("=2")   // => "50.00"
 */
export function cadd(...nums: (NumOrStr | ChainValue)[]): ChainValue;

/**
 * 链式减法起始
 * @example
 * csub(10, 3)()             // => "7"
 * csub(100, 50).div(2)()    // => "25"
 */
export function csub(first: NumOrStr | ChainValue, ...rest: (NumOrStr | ChainValue)[]): ChainValue;

/**
 * 链式乘法起始
 * @example
 * cmul(2, 3, 4)()           // => "24"
 * cmul(10).add(5)()         // => "15"
 */
export function cmul(...nums: (NumOrStr | ChainValue)[]): ChainValue;

/**
 * 链式除法起始
 * @example
 * cdiv(100, 2)()            // => "50"
 * cdiv(100, 2, 5)()         // => "10"
 */
export function cdiv(first: NumOrStr | ChainValue, ...rest: (NumOrStr | ChainValue)[]): ChainValue;

/**
 * 链式取模起始
 * @example
 * cmod(10, 3)()             // => "1"
 */
export function cmod(first: NumOrStr | ChainValue, ...rest: (NumOrStr | ChainValue)[]): ChainValue;

/**
 * 链式幂运算起始
 * @example
 * cpow(2, 3)()              // => "8"
 */
export function cpow(first: NumOrStr | ChainValue, ...rest: (NumOrStr | ChainValue)[]): ChainValue;

/**
 * 链式整除起始
 * @example
 * cidiv(10, 3)()            // => "3"
 */
export function cidiv(first: NumOrStr | ChainValue, ...rest: (NumOrStr | ChainValue)[]): ChainValue;

// ==================== 计算模式 ====================

/**
 * 计算模式类型
 */
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;
        _compact?: string;
    };

/**
 * 单位转换映射类型（输出单位为key）
 */
export type UnitConvertOut = Record<string, Record<string, UnitConvertRule> & {
    _position?: 'before' | 'after' | 'middle';
    _thousands?: string;
    _compact?: string;
}>;

/**
 * 单位转换映射类型（输入单位为key）
 */
export type UnitConvertIn = Record<string, Record<string, UnitConvertRule>>;

/**
 * 千分位预设名称（系统内置）
 * - en: 英文/国际标准 (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 = 'en' | 'eu' | 'swiss' | 'space' | 'fr' | 'indian' | 'wan';

/**
 * 紧凑格式预设名称（系统内置）
 * - en: 英文/国际通用 (1.23K, 1.23M, 1.23B, 1.23T)
 * - cn: 中文千进制 (1.23千, 1.23百万, 1.23十亿, 1.23万亿)
 * - wan: 万进制 (1.23万, 1.23亿, 1.23万亿)
 * - storage: 存储单位 (1KB, 1MB, 1GB, 1TB - 1024进制)
 * - indian: 印度格式 (1.23K, 1.23L, 1.23Cr - 阶梯[1000,100,100])
 */
export type CompactPresetName = 'en' | 'cn' | 'wan' | 'storage' | 'indian';

/**
 * 千分位预设配置类型
 */
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 CompactPreset =
    | string[]  // 简写形式：只有符号数组，step 默认 1000
    | {         // 完整形式：包含 symbols 和 step
        symbols: string[];
        step?: number | number[];
    }
    | ((num_str: string, context: {  // 自定义函数形式
        decimals: number;
        options: any;
        current_unit?: string;
    }) => {
        sign: string;
        number: string;
        unit: string;
        formatted: string;
    } | string);  // 可以返回对象或字符串

/**
 * 全局配置项（只能通过 set_config 设置）
 */
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;
    /** 默认舍入模式 */
    _default_round?: string;
    /** 默认格式化字符串（全局配置） */
    _fmt?: string;
    /** 内置函数映射 */
    _builtin_functions?: Record<string, (...args: any[]) => any>;

    // ==================== 紧凑格式配置 ====================
    /** 紧凑格式预设配置（全局配置） */
    _compact?: Record<string, CompactPreset>;
    /** 默认紧凑格式预设名称 */
    _compact_default?: string;

    // ==================== 格式化分组配置 ====================
    /** 格式化分组（全局配置） */
    _fmt_groups?: Record<string, 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_compact_map?: Record<string, string>;

    // ==================== 千分位配置 ====================
    /** 千分位预设配置 */
    _thousands?: Record<string, ThousandsPreset>;
    /** 默认千分位预设名称 */
    _thousands_default?: string;

    // ==================== 快捷语法配置 ====================
    /** 快捷语法前缀（:xxx 等同于 _shortcut_prefix:xxx），默认 '!u' */
    _shortcut_prefix?: string;

    // ==================== 多路取值配置 ====================
    /** 多路取值时视为空值的值数组（全局配置，运行时选项可覆盖） */
    _empty_values?: any[];
    /** 多路取值时自定义空值判断函数（全局配置，运行时选项可覆盖） */
    _empty_check?: (value: any, path?: string) => boolean;
}

/**
 * 设置全局配置
 * @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: GlobalConfig): void;

/**
 * 获取全局配置
 * @param key 配置项名称，不传则返回全部配置
 * @returns 配置值或全部配置对象
 * @example
 * get_config('_compute_mode')  // => 'decimal'
 * get_config()                 // => { _compute_mode: 'decimal', ... }
 */
export function get_config(): GlobalConfig;
export function get_config<K extends keyof GlobalConfig>(key: K): GlobalConfig[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 GlobalConfig): void;
export function reset_config(keys: (keyof GlobalConfig)[]): void;

/**
 * 运算符方法类型（跟随 _compute_mode 配置变化）
 */
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;
}

/**
 * 原始运算符对象（跟随 _compute_mode 配置变化）
 */
export const ops: Ops;

/**
 * 加载 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;

// ==================== d 前缀原始运算函数（decimal 模式） ====================
// 这些函数始终使用 decimal.js 进行计算，不受 _compute_mode 配置影响

// 基础运算
export function dadd(a: string, b: string): string;
export function dsub(a: string, b: string): string;
export function dmul(a: string, b: string): string;
export function ddiv(a: string, b: string): string;
export function dmod(a: string, b: string): string;
export function dpow(a: string, b: string): string;
export function didiv(a: string, b: string): string;

// 一元运算
export function dabs(a: string): string;
export function dneg(a: string): string;
export function dsqrt(a: string): string;
export function dcbrt(a: string): string;

// 指数对数
export function dexp(a: string): string;
export function dln(a: string): string;
export function dlog(a: string, base: string): string;
export function dlog2(a: string): string;
export function dlog10(a: string): string;

// 三角函数
export function dsin(a: string): string;
export function dcos(a: string): string;
export function dtan(a: string): string;
export function dasin(a: string): string;
export function dacos(a: string): string;
export function datan(a: string): string;

// 双曲函数
export function dsinh(a: string): string;
export function dcosh(a: string): string;
export function dtanh(a: string): string;
export function dasinh(a: string): string;
export function dacosh(a: string): string;
export function datanh(a: string): string;

// 取整
export function dfloor(a: string): string;
export function dceil(a: string): string;
export function dtrunc(a: string): string;
export function dround(a: string): string;

// 比较
export function dmax(a: string, b: string): string;
export function dmin(a: string, b: string): string;
export function dcompare(a: string, b: string): number;
export function deq(a: string, b: string): boolean;
export function dlt(a: string, b: string): boolean;
export function dgt(a: string, b: string): boolean;
export function dlte(a: string, b: string): boolean;
export function dgte(a: string, b: string): boolean;

// ==================== b 前缀原始运算函数（bigint 模式） ====================
// 这些函数始终使用 BigInt 进行计算，不受 _compute_mode 配置影响

// 基础运算
export function badd(a: string, b: string): string;
export function bsub(a: string, b: string): string;
export function bmul(a: string, b: string): string;
export function bdiv(a: string, b: string): string;
export function bmod(a: string, b: string): string;
export function bpow(a: string, b: string): string;
export function bidiv(a: string, b: string): string;

// 一元运算
export function babs(a: string): string;
export function bneg(a: string): string;
export function bsqrt(a: string): string;
export function bcbrt(a: string): string;

// 指数对数
export function bexp(a: string): string;
export function bln(a: string): string;
export function blog(a: string, base: string): string;
export function blog2(a: string): string;
export function blog10(a: string): string;

// 三角函数
export function bsin(a: string): string;
export function bcos(a: string): string;
export function btan(a: string): string;
export function basin(a: string): string;
export function bacos(a: string): string;
export function batan(a: string): string;

// 双曲函数
export function bsinh(a: string): string;
export function bcosh(a: string): string;
export function btanh(a: string): string;
export function basinh(a: string): string;
export function bacosh(a: string): string;
export function batanh(a: string): string;

// 取整
export function bfloor(a: string): string;
export function bceil(a: string): string;
export function btrunc(a: string): string;
export function bround(a: string): string;

// 比较
export function bmax(a: string, b: string): string;
export function bmin(a: string, b: string): string;
export function bcompare(a: string, b: string): number;
export function beq(a: string, b: string): boolean;
export function blt(a: string, b: string): boolean;
export function bgt(a: string, b: string): boolean;
export function blte(a: string, b: string): boolean;
export function bgte(a: string, b: string): boolean;

// ==================== w 前缀原始运算函数（wasm 模式） ====================
// 这些函数使用 WASM 进行计算，首次调用时自动触发 WASM 加载
// 加载完成前使用 decimal 模式兜底

// 基础运算
export function wadd(a: string, b: string): string;
export function wsub(a: string, b: string): string;
export function wmul(a: string, b: string): string;
export function wdiv(a: string, b: string): string;
export function wmod(a: string, b: string): string;
export function wpow(a: string, b: string): string;
export function widiv(a: string, b: string): string;

// 一元运算
export function wabs(a: string): string;
export function wneg(a: string): string;
export function wsqrt(a: string): string;
export function wcbrt(a: string): string;

// 指数对数
export function wexp(a: string): string;
export function wln(a: string): string;
export function wlog(a: string, base: string): string;
export function wlog2(a: string): string;
export function wlog10(a: string): string;

// 三角函数
export function wsin(a: string): string;
export function wcos(a: string): string;
export function wtan(a: string): string;
export function wasin(a: string): string;
export function wacos(a: string): string;
export function watan(a: string): string;

// 双曲函数
export function wsinh(a: string): string;
export function wcosh(a: string): string;
export function wtanh(a: string): string;
export function wasinh(a: string): string;
export function wacosh(a: string): string;
export function watanh(a: string): string;

// 取整
export function wfloor(a: string): string;
export function wceil(a: string): string;
export function wtrunc(a: string): string;
export function wround(a: string): string;

// 比较
export function wmax(a: string, b: string): string;
export function wmin(a: string, b: string): string;
export function wcompare(a: string, b: string): number;
export function weq(a: string, b: string): boolean;
export function wlt(a: string, b: string): boolean;
export function wgt(a: string, b: string): boolean;
export function wlte(a: string, b: string): boolean;
export function wgte(a: string, b: string): boolean;