调试模式

调试模式用于输出表达式的详细计算过程，包括变量解析、计算步骤等信息。帮助开发者理解和排查表达式问题。

启用方式

通过 _debug 配置启用：

calc('price * qty * (1 - discount)', {
  price: 100,
  qty: 3,
  discount: 0.1,
  _debug: true
})

// 控制台输出：
// ┌──────────────────────────────────────────────────┐
// │ [a-calc debug]                                   │
// ├──────────────────────────────────────────────────┤
// │ 表达式: price * qty * (1 - discount)             │
// │                                                  │
// │ 变量:                                            │
// │   price = 100                                    │
// │   qty = 3                                        │
// │   discount = 0.1                                 │
// │                                                  │
// │ 步骤:                                            │
// │   1. price * qty * (1 - discount)                │
// │      → 100 * 3 * ( 1 - 0.1 ) = 270               │
// │                                                  │
// │ 结果: "270"                                      │
// └──────────────────────────────────────────────────┘

控制台输出配置

默认情况下，_debug: true 会输出调试信息到控制台。可通过全局配置关闭：

import { set_config } from 'a-calc'

// 关闭控制台输出
set_config({ _debug_console: false })

// 此时 _debug: true 不会输出到控制台
calc('1 + 2', { _debug: true })  // 不输出

// 重新开启
set_config({ _debug_console: true })

回调获取调试信息

通过 _on_debug 回调获取结构化的调试信息。回调不受 _debug_console 全局配置影响，只要提供就会被调用：

calc('price * qty', {
  price: 100,
  qty: 3,
  _debug: true,
  _on_debug: (info) => {
    console.log(info)
    // 或发送到日志服务
    // logService.send(info)
  }
})

回调参数结构

{
  expression: 'price * qty',              // 原始表达式
  variables: {                            // 变量及取值
    price: 100,
    qty: 3
  },
  steps: [                                // 计算步骤
    {
      expression: 'price * qty',
      substituted: '100 * 3',
      result: '300'
    }
  ],
  format: null,                           // 格式化规格（如果有）
  result: '300'                           // 最终结果
}

带格式化的调试

calc('price * qty | =2', {
  price: 100,
  qty: 3,
  _debug: true
})

// 输出包含格式化信息：
// ┌──────────────────────────────────────────────────┐
// │ [a-calc debug]                                   │
// ├──────────────────────────────────────────────────┤
// │ 表达式: price * qty | =2                         │
// │                                                  │
// │ 变量:                                            │
// │   price = 100                                    │
// │   qty = 3                                        │
// │                                                  │
// │ 步骤:                                            │
// │   1. price * qty                                 │
// │      → 100 * 3 = 300                             │
// │                                                  │
// │ 格式化: | =2                                     │
// │                                                  │
// │ 结果: "300.00"                                   │
// └──────────────────────────────────────────────────┘

条件表达式的调试

calc('x > 0 ? x * 2 : 0', { x: 5, _debug: true })

// 输出：
// 表达式: x > 0 ? x * 2 : 0
// 变量: { x: 5 }
// 步骤:
//   1. x > 0 ? x * 2 : 0
//      → 5 > 0 ? 5 * 2 : 0 = 10
// 结果: "10"

函数调用的调试

calc('sqrt(pow(a, 2) + pow(b, 2))', { a: 3, b: 4, _debug: true })

// 输出：
// 表达式: sqrt(pow(a, 2) + pow(b, 2))
// 变量: { a: 3, b: 4 }
// 步骤:
//   1. sqrt(pow(a, 2) + pow(b, 2))
//      → sqrt ( pow ( 3 , 2 ) + pow ( 4 , 2 ) ) = 5
// 结果: "5"

错误调试

当表达式出错时，调试信息也会显示错误：

calc('a / b', { a: 10, _debug: true })

// 输出包含错误信息：
// 表达式: a / b
// 变量: { a: 10 }
// 错误: 变量 b 未定义
// 结果: "-"

性能考虑

调试模式会带来额外开销，生产环境建议关闭控制台输出：

import { set_config } from 'a-calc'

// 通过环境变量控制
set_config({ _debug_console: process.env.NODE_ENV === 'development' })

当不使用 _debug: true 时，调试相关代码路径完全跳过，无性能损耗。

实际应用

开发调试

// 开发时快速定位问题
calc('complex * expression / here', {
  ...data,
  _debug: true
})

日志记录

import { set_config } from 'a-calc'

// 关闭控制台，仅通过回调记录
set_config({ _debug_console: false })

calc('price * qty', {
  ...order,
  _debug: true,
  _on_debug: (info) => {
    logger.info('计算日志', info)
  }
})

测试验证

// 在测试中验证计算步骤
let debugInfo
calc('a + b * c', {
  a: 1, b: 2, c: 3,
  _debug: true,
  _on_debug: (info) => { debugInfo = info }
})

expect(debugInfo.result).toBe('7')
expect(debugInfo.variables).toEqual({ a: 1, b: 2, c: 3 })