调试模式 API

调试模式通过配置项集成在 calc 函数中。

配置选项

_debug

启用调试模式。

类型	默认值
boolean	false

calc('a + b', { a: 1, b: 2, _debug: true })

_on_debug

调试信息回调函数。不受全局配置影响，只要提供就会被调用。

类型
(info: DebugInfo) => void

calc('a + b', {
  a: 1, b: 2,
  _debug: true,
  _on_debug: (info) => {
    console.log(info.result)
  }
})

set_config(config)

设置全局配置。

参数

参数	类型	描述
config	object	配置对象

配置项

基础配置

配置项	类型	默认值	描述
_debug_console	boolean	true	调试信息是否输出到控制台
_error	any	'-'	全局错误返回值
_angle_unit	'deg' | 'rad'	'deg'	角度单位
_compute_mode	'decimal' | 'bigint' | 'wasm'	'decimal'	计算模式
_div_precision	number	20	BigInt 模式除法精度

单位转换配置

配置项	类型	默认值	描述
_unit_convert_out	object	undefined	单位转换映射（输出单位为 key）
_unit_convert_in	object	undefined	单位转换映射（输入单位为 key）
_unit_default_out	string | string[]	undefined	默认输出单位
_unit_default_in	string | string[]	undefined	默认输入单位
_unit_default_position	'before' | 'after' | 'middle'	undefined	默认单位位置
_unit_position_map	object	undefined	单位到位置的映射
_unit_thousands_map	object	undefined	单位到千分位预设的映射
_unit_compact_map	object	undefined	单位到紧凑格式预设的映射

紧凑格式配置

配置项	类型	默认值	描述
_compact	object	undefined	紧凑格式预设配置
_compact_symbols	string[]	undefined	紧凑格式单位数组
_compact_step	number | number[]	undefined	紧凑格式阶梯

千分位配置

配置项	类型	默认值	描述
_thousands	object	undefined	千分位预设配置

示例

import { set_config } from 'a-calc'

// 关闭调试信息的控制台输出
set_config({ _debug_console: false })

// 设置全局错误返回值
set_config({ _error: '--' })

// 切换为弧度制
set_config({ _angle_unit: 'rad' })

// 设置全局单位转换配置
set_config({
  _unit_convert_out: {
    '元': { '分': 0.01 },
    '$': { '￠': 0.01 }
  },
  _unit_default_out: '元',
  _unit_default_in: '分',
  _unit_default_position: 'after'
})

// 设置全局千分位预设
set_config({
  _thousands: {
    'cn': { sep: ',', point: '.', grouping: [3] },
    'de': { sep: '.', point: ',', grouping: [3] }
  }
})

// 设置全局紧凑格式预设
set_config({
  _compact: {
    'cn': { symbols: ['', '万', '亿', '万亿'], step: 10000 },
    'en': { symbols: ['', 'K', 'M', 'B', 'T'], step: 1000 }
  }
})

get_config(key?)

获取全局配置。

参数

参数	类型	描述
key	string	可选，配置键名

返回值

• 传入 key：返回对应配置值
• 不传 key：返回整个配置对象的副本

示例

import { get_config } from 'a-calc'

// 获取单个配置
get_config('_debug_console')  // true
get_config('_compute_mode')   // 'decimal'
get_config('_unit_convert_out')  // undefined 或用户设置的值

// 获取全部配置
get_config()  // { _debug_console: true, _error: '-', ... }

reset_config(keys?)

重置全局配置到默认值。

参数

参数	类型	描述
keys	string | string[]	可选，要重置的配置键名

调用方式

• 不传参数：重置所有配置到默认值
• 传入单个 key：重置指定配置
• 传入 key 数组：重置多个配置

示例

import { set_config, reset_config } from 'a-calc'

// 设置一些配置
set_config({
  _error: 0,
  _unit_convert_out: { '元': { '分': 0.01 } },
  _unit_default_out: '元'
})

// 重置单个配置
reset_config('_error')  // _error 恢复为 '-'

// 重置多个配置
reset_config(['_unit_convert_out', '_unit_default_out'])

// 重置所有配置
reset_config()  // 所有配置恢复默认值

在单元测试中使用

reset_config 特别适合在单元测试中使用，确保每个测试用例都在干净的配置状态下运行：

// 在测试框架的 beforeEach/afterEach 中重置配置
beforeEach(() => {
  reset_config()
})

DebugInfo 类型

回调函数接收的调试信息对象：

interface DebugInfo {
  expression: string           // 原始表达式
  variables: Record<string, any>  // 变量及其值
  steps: Array<{
    expression: string        // 步骤表达式
    substituted: string       // 替换后的表达式
    result: string           // 步骤结果
  }>
  format: string | null       // 格式化规格
  result: any                 // 最终结果
  error?: string              // 错误信息（如果有）
}

控制台输出格式

┌──────────────────────────────────────────────────┐
│ [a-calc debug]                                   │
├──────────────────────────────────────────────────┤
│ 表达式: price * qty                              │
│                                                  │
│ 变量:                                            │
│   price = 100                                    │
│   qty = 3                                        │
│                                                  │
│ 步骤:                                            │
│   1. price * qty                                 │
│      → 100 * 3 = 300                             │
│                                                  │
│ 结果: "300"                                      │
└──────────────────────────────────────────────────┘