Debug Mode

Debug mode prints detailed calculation traces to help diagnose expression issues.

Enable

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

// Console output:
// ┌──────────────────────────────────────────────────┐
// │ [a-calc debug]                                   │
// ├──────────────────────────────────────────────────┤
// │ Expression: price * qty * (1 - discount)         │
// │                                                  │
// │ Variables:                                       │
// │   price = 100                                    │
// │   qty = 3                                        │
// │   discount = 0.1                                 │
// │                                                  │
// │ Steps:                                           │
// │   1. price * qty * (1 - discount)                │
// │      → 100 * 3 * ( 1 - 0.1 ) = 270              │
// │                                                  │
// │ Result: "270"                                    │
// └──────────────────────────────────────────────────┘

Disable Console Output

import { set_config } from "a-calc";

set_config({ _debug_console: false });
// _debug: true will no longer print to console

Callback for Structured Data

calc("price * qty", {
  price: 100,
  qty: 3,
  _debug: true,
  _on_debug: (info) => {
    console.log(info);
    // or send to a logging service
  },
});

Callback Structure

{
  expression: 'price * qty',
  variables: { price: 100, qty: 3 },
  steps: [
    {
      expression: 'price * qty',
      substituted: '100 * 3',
      result: '300'
    }
  ],
  format: null,
  result: '300'
}

Production Usage

import { set_config } from "a-calc";

// Only enable in development
set_config({ _debug_console: process.env.NODE_ENV === "development" });

When _debug is not set, all debug code paths are skipped — zero performance overhead.

Testing

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 });