@wzo/calc 0.0.1

package/src/utils/format.ts

@@ -0,0 +1,366 @@
+// Number formatting: parse token string → options → format
+import type { IGlobalConfig } from './config'
+import { getConfig } from './config'
+import { evaluate } from './parser'
+import { abs, cmp, div, format as fmtDecimal, mul, parse, roundBanker, roundCeil, roundHalfUp, truncate } from './precision'
+
+/**
+ * Rounding strategy. Includes JS-style aliases: `'round'`≡`'halfUp'` (same as `Math.round`),
+ * `'trunc'`≡`'truncate'` (same as `Math.trunc`, truncate toward zero),
+ * `'halfEven'`≡`'banker'` (same as `Intl.NumberFormat` `roundingMode: 'halfEven'`, banker's rounding).
+ */
+export type Rounding = 'truncate' | 'trunc' | 'halfUp' | 'round' | 'banker' | 'halfEven' | 'ceil'
+
+// Internal canonical rounding names (the 4 modes recognized by applyRounding)
+type Canon = 'truncate' | 'halfUp' | 'banker' | 'ceil'
+
+/**
+ * Format options object — passed to {@link fmt} / `calc`'s `_fmt` / chaining terminators.
+ * Equivalent to a format token string but with full type hints.
+ */
+export interface IFormat {
+    /** Decimal places: number = fixed (`=N`); object = range (`{ max }`≡`<=N`, `{ min }`≡`>=N`) */
+    decimals?: number | { min?: number, max?: number }
+    /** Rounding strategy (`~5`/`~6`/`~-`/`~+`) */
+    rounding?: Rounding
+    /** Thousands separator: `true` = US style; or `'us'`/`'eu'`/`'in'` (≡ `,` / `!t:preset`) */
+    thousands?: boolean | 'us' | 'eu' | 'in'
+    /** Compact notation: `true` = K/M/B/T; or `'zh'` = 万/亿 (≡ `!c` / `!c:preset`) */
+    compact?: boolean | 'zh'
+    /** Clamp value to `[min, max]`; out-of-range values are clamped to the boundary (≡ `[min,max]`) */
+    clamp?: [number | string, number | string]
+    /** Output form (mutually exclusive): accepts human-readable words or token symbols (≡ `%%` / `//` / `!e` / `!n`) */
+    output?: 'percent' | '%%' | 'fraction' | '//' | 'scientific' | 'e' | 'number' | 'num'
+    /** Show explicit plus sign (≡ `+`) */
+    plus?: boolean
+    /** Left-pad the integer part with zeros to N digits (≡ `!i:N`) */
+    pad?: number
+}
+
+// Flat internal structure (output of normalizeFormat / input of formatValue)
+export interface IFormatOpts {
+    fixed?: number // =N
+    max?: number // <=N
+    min?: number // >=N
+    thousands?: boolean // ,
+    thousandsPreset?: 'us' | 'eu' | 'in'
+    plus?: boolean // +
+    percent?: boolean // %%
+    fraction?: boolean // //
+    scientific?: boolean // !e
+    asNumber?: boolean // !n
+    compact?: boolean // !c
+    compactPreset?: string // !c:zh (Chinese 万/亿)
+    intPad?: number // !i:N
+    rounding?: Canon // ~- / ~5 / ~6 / ~+
+    clampMin?: string // [min,max] lower bound
+    clampMax?: string // [min,max] upper bound
+}
+
+// IFormat.rounding (including aliases) → internal canonical name
+const ROUNDING_ALIAS: Record<Rounding, Canon> = {
+    truncate: 'truncate',
+    trunc: 'truncate',
+    halfUp: 'halfUp',
+    round: 'halfUp',
+    banker: 'banker',
+    halfEven: 'banker',
+    ceil: 'ceil',
+}
+
+// IFormat.output (human-readable word / token symbol) → flat boolean field
+const OUTPUT_FLAG: Record<string, 'percent' | 'fraction' | 'scientific' | 'asNumber'> = {
+    'percent': 'percent',
+    '%%': 'percent',
+    'fraction': 'fraction',
+    '//': 'fraction',
+    'scientific': 'scientific',
+    'e': 'scientific',
+    'number': 'asNumber',
+    'num': 'asNumber',
+}
+
+// ───── Module-level regexes ─────
+const RE_THOUSANDS_GROUPS = /\B(?=(?:\d{3})+(?!\d))/g
+const RE_TRAIL_ZERO = /0+$/
+const RE_DOT_END = /\.$/
+const RE_ZERO_VAL = /^0+(?:\.0+)?$/
+const RE_COMMA_GLOBAL = /,/g
+
+// ───── Rounding ─────
+const applyRounding = (value: string, decimals: number, mode: Canon): string => {
+    switch (mode) {
+        case 'halfUp': return roundHalfUp(value, decimals)
+        case 'banker': return roundBanker(value, decimals)
+        case 'ceil': return roundCeil(value, decimals)
+        case 'truncate':
+        default: return truncate(value, decimals)
+    }
+}
+
+// ───── Thousands separator (integer part only) ─────
+const applyThousands = (intStr: string, preset?: 'us' | 'eu' | 'in'): string => {
+    if (preset === 'in') {
+        // Indian: last 3 digits, then groups of 2 (e.g. 123,45,678)
+        if (intStr.length <= 3) return intStr
+        const last3 = intStr.slice(-3)
+        const restPart = intStr.slice(0, -3)
+        const parts: string[] = []
+        let r = restPart
+        while (r.length > 2) {
+            parts.unshift(r.slice(-2))
+            r = r.slice(0, -2)
+        }
+        if (r) parts.unshift(r)
+        return `${parts.join(',')},${last3}`
+    }
+    return intStr.replace(RE_THOUSANDS_GROUPS, ',')
+}
+
+// ───── Compact presets ─────
+const COMPACT_PRESETS: Record<string, Array<{ scale: number, suffix: string }>> = {
+    default: [
+        { scale: 12, suffix: 'T' },
+        { scale: 9, suffix: 'B' },
+        { scale: 6, suffix: 'M' },
+        { scale: 3, suffix: 'K' },
+    ],
+    // Chinese: 万 (10k) / 亿 (100M)
+    zh: [
+        { scale: 12, suffix: '万亿' },
+        { scale: 8, suffix: '亿' },
+        { scale: 4, suffix: '万' },
+    ],
+}
+
+const applyCompact = (value: string, preset: string | undefined): { num: string, suffix: string } => {
+    const presets = COMPACT_PRESETS[preset || 'default'] || COMPACT_PRESETS.default!
+    const absValue = abs(value)
+    for (const p of presets) {
+        const threshold = `1${'0'.repeat(p.scale)}`
+        if (cmp(absValue, threshold) >= 0) {
+            return { num: div(value, threshold, 20), suffix: p.suffix }
+        }
+    }
+    return { num: value, suffix: '' }
+}
+
+// ───── Scientific notation ─────
+const applyScientific = (value: string): string => {
+    const d = parse(value)
+    if (d.digits === 0n) return '0e+0'
+    const digitStr = d.digits.toString()
+    const mantissaExp = digitStr.length - 1
+    const e = mantissaExp - d.exp
+    const mantissa = digitStr.length === 1
+        ? digitStr
+        : `${digitStr[0]}.${digitStr.slice(1).replace(RE_TRAIL_ZERO, '')}`.replace(RE_DOT_END, '')
+    const sign = d.sign < 0 ? '-' : ''
+    return `${sign}${mantissa}e${e >= 0 ? '+' : ''}${e}`
+}
+
+// ───── Fraction (reduced to lowest terms) ─────
+const gcd = (a: bigint, b: bigint): bigint => b === 0n ? a : gcd(b, a % b)
+
+const applyFraction = (value: string): string => {
+    const d = parse(value)
+    if (d.digits === 0n) return '0'
+    if (d.exp === 0) return d.sign < 0 ? `-${d.digits}/1` : `${d.digits}/1`
+    let num = d.digits
+    let den = 10n ** BigInt(d.exp)
+    const g = gcd(num, den)
+    num /= g
+    den /= g
+    return `${d.sign < 0 ? '-' : ''}${num}/${den}`
+}
+
+// ───── Decimal / integer zero-padding ─────
+const padDecimals = (v: string, n: number): string => {
+    const dot = v.indexOf('.')
+    if (n === 0) return dot === -1 ? v : v.slice(0, dot)
+    if (dot === -1) return `${v}.${'0'.repeat(n)}`
+    const fracLen = v.length - dot - 1
+    if (fracLen >= n) return v
+    return v + '0'.repeat(n - fracLen)
+}
+
+const padIntegerZeros = (v: string, n: number): string => {
+    let sign = ''
+    let s = v
+    if (s.startsWith('-')) {
+        sign = '-'
+        s = s.slice(1)
+    } else if (s.startsWith('+')) {
+        sign = '+'
+        s = s.slice(1)
+    }
+    const dot = s.indexOf('.')
+    const intPart = dot === -1 ? s : s.slice(0, dot)
+    const rest = dot === -1 ? '' : s.slice(dot)
+    if (intPart.length >= n) return sign + intPart + rest
+    return sign + intPart.padStart(n, '0') + rest
+}
+
+// ───── Thousands separator + EU format ─────
+const applyThousandsAndPreset = (v: string, preset?: 'us' | 'eu' | 'in'): string => {
+    let sign = ''
+    let s = v
+    if (s.startsWith('-')) {
+        sign = '-'
+        s = s.slice(1)
+    } else if (s.startsWith('+')) {
+        sign = '+'
+        s = s.slice(1)
+    }
+    const dot = s.indexOf('.')
+    const intPart = dot === -1 ? s : s.slice(0, dot)
+    const fracPart = dot === -1 ? '' : s.slice(dot + 1)
+    const grouped = applyThousands(intPart, preset)
+    if (preset === 'eu') {
+        // EU style: thousands separator is '.', decimal separator is ','
+        const groupedEu = grouped.replace(RE_COMMA_GLOBAL, '.')
+        return sign + groupedEu + (fracPart ? `,${fracPart}` : '')
+    }
+    return sign + grouped + (fracPart ? `.${fracPart}` : '')
+}
+
+// ───── Final decoration ─────
+const finalDecorate = (v: string, opts: IFormatOpts, compactSuffix: string): string | number => {
+    let s = v
+    if (compactSuffix) s += compactSuffix
+    if (opts.percent) s += '%'
+    if (opts.asNumber) return Number(s)
+    return s
+}
+
+/**
+ * Formats a numeric string according to {@link IFormatOpts} (rounding, zero-padding,
+ * thousands separator, compact notation, percent, etc.).
+ *
+ * Most callers should prefer {@link fmt}; this function accepts already-normalized flat options.
+ *
+ * @param value Canonical numeric string (e.g. the result of a precision arithmetic operation)
+ * @param opts Formatting options produced by {@link normalizeFormat}
+ * @returns Formatted result — `number` when `output: 'number'`, `string` otherwise
+ */
+export const formatValue = (value: string, opts: IFormatOpts): string | number => {
+    let v = value
+
+    // Clamp: constrain the value to [min, max] before any further formatting
+    if (opts.clampMin !== undefined && cmp(v, opts.clampMin) < 0) v = opts.clampMin
+    if (opts.clampMax !== undefined && cmp(v, opts.clampMax) > 0) v = opts.clampMax
+
+    if (opts.percent) v = mul(v, '100')
+
+    let compactSuffix = ''
+    if (opts.compact) {
+        const c = applyCompact(v, opts.compactPreset)
+        v = c.num
+        compactSuffix = c.suffix
+    }
+
+    if (opts.fraction) return finalDecorate(applyFraction(v), opts, compactSuffix)
+    if (opts.scientific) return finalDecorate(applyScientific(v), opts, compactSuffix)
+
+    const rounding = opts.rounding || 'truncate'
+    if (opts.fixed !== undefined) {
+        v = applyRounding(v, opts.fixed, rounding)
+        v = padDecimals(v, opts.fixed)
+    } else {
+        if (opts.max !== undefined) v = applyRounding(v, opts.max, rounding)
+        if (opts.min !== undefined) v = padDecimals(v, opts.min)
+    }
+
+    if (opts.intPad !== undefined) v = padIntegerZeros(v, opts.intPad)
+    if (opts.thousands) v = applyThousandsAndPreset(v, opts.thousandsPreset)
+
+    if (opts.plus && !v.startsWith('-') && !RE_ZERO_VAL.test(v)) v = `+${v}`
+
+    return finalDecorate(v, opts, compactSuffix)
+}
+
+/**
+ * Normalizes a high-level {@link IFormat} object into the internal flat options structure.
+ *
+ * @param format An {@link IFormat} object
+ * @returns Flat {@link IFormatOpts}
+ */
+export const normalizeFormat = (format: IFormat | undefined): IFormatOpts => {
+    if (!format) return {}
+    const o: IFormatOpts = {}
+    const f = format
+    if (typeof f.decimals === 'number') {
+        o.fixed = f.decimals
+    } else if (f.decimals) {
+        if (f.decimals.max !== undefined) o.max = f.decimals.max
+        if (f.decimals.min !== undefined) o.min = f.decimals.min
+    }
+    if (f.rounding) o.rounding = ROUNDING_ALIAS[f.rounding]
+    if (f.thousands) {
+        o.thousands = true
+        if (f.thousands !== true) o.thousandsPreset = f.thousands
+    }
+    if (f.compact) {
+        o.compact = true
+        if (f.compact !== true) o.compactPreset = f.compact
+    }
+    if (f.clamp) {
+        o.clampMin = String(f.clamp[0])
+        o.clampMax = String(f.clamp[1])
+    }
+    const outFlag = f.output && OUTPUT_FLAG[f.output]
+    if (outFlag) o[outFlag] = true
+    if (f.plus) o.plus = true
+    if (f.pad !== undefined) o.intPad = f.pad
+    return o
+}
+
+/** Options for {@link fmt}: formatting fields (see {@link IFormat}) plus `_`-prefixed control options */
+export interface IFmtOptions extends IFormat {
+    /** Error fallback value: defaults to the global `_error` (typically `'-'`). **Only `fmt` has a fallback */
+    _error?: string | number
+    /** Division precision used when evaluating expressions (defaults to the global `_precision`) */
+    _precision?: number
+    /** Enable unit mode (`%` etc., same as `calc`'s `_unit`) */
+    _unit?: boolean
+}
+
+const RE_PERCENT = /%/
+
+/**
+ * Display-oriented formatting: the display counterpart of {@link calc} — same API,
+ * **supports arithmetic** (the first argument may be an arithmetic expression string),
+ * but **returns `_error` as a fallback on failure instead of throwing**, making it safe
+ * for direct use in template rendering (e.g. `{{ fmt(`${price} * ${qty}`, { decimals: 2 }) }}`).
+ *
+ * - Pass a `string` ⇒ evaluate as an arithmetic expression, then format (`fmt('1 + 2 * 3')` ⇒ `'7'`)
+ * - Pass a `number` / `bigint` ⇒ format directly
+ * - On error (invalid expression, etc.) ⇒ return the `_error` fallback
+ *   (local `options._error` takes precedence over the global default `'-'`)
+ *
+ * @returns Formatted result; the `_error` fallback value on failure
+ * @example
+ * fmt(1234.5, { decimals: 2, thousands: true }) // '1,234.50'
+ * fmt('999.99 * 3', { decimals: 2 })            // '2,999.97' (evaluate first, then format)
+ * fmt('bad expr')                               // '-' (fallback, does not throw)
+ */
+export function fmtWith(cfg: IGlobalConfig, value: string | number | bigint, options?: IFmtOptions): string | number {
+    try {
+        const v = typeof value === 'string'
+            ? evaluate(value, { unit: !!options?._unit, precision: options?._precision ?? cfg._precision, trace: undefined })
+            : fmtDecimal(parse(value))
+        const opts = normalizeFormat(options)
+        const out = formatValue(v, opts)
+        // Unit mode: if the expression contains % and no explicit output form is set, append % to the result
+        if (typeof value === 'string' && options?._unit && RE_PERCENT.test(value) && typeof out === 'string'
+            && !opts.percent && !opts.fraction && !opts.scientific && !opts.asNumber) {
+            return `${out}%`
+        }
+        return out
+    } catch {
+        // Fallback: local _error takes precedence; otherwise use the global _error (default '-')
+        return options?._error !== undefined ? options._error : cfg._error
+    }
+}
+
+export const fmt = (value: string | number | bigint, options?: IFmtOptions): string | number => fmtWith(getConfig(), value, options)

package/src/utils/parser.ts

@@ -0,0 +1,310 @@
+// Expression parsing + evaluation (pure arithmetic: four operations + parentheses + math functions;
+// variables are not supported — embed values via template interpolation)
+// Grammar (lowest → highest precedence):
+//   addSub  := mulDiv (('+' | '-') mulDiv)*
+//   mulDiv  := unary (('*' | '/') unary)*
+//   unary   := ('+' | '-')? primary
+//   primary := NUMBER | IDENT | FN '(' args ')' | '(' addSub ')'
+
+import { abs, add, cmp, div, mul, neg, sub, truncate } from './precision'
+
+// ───── Tokenizer ─────
+type TokenType
+    = | 'NUMBER' | 'IDENT' | 'UNIT'
+        | 'PLUS' | 'MINUS' | 'STAR' | 'SLASH'
+        | 'LPAREN' | 'RPAREN' | 'COMMA'
+        | 'EOF'
+
+interface IToken { type: TokenType, value: string, pos: number }
+
+const RE_WS = /\s/
+const RE_DIGIT = /\d/
+const RE_NUM_BODY = /[\d.]/
+// CJK Unified Ideographs range: U+4E00 ~ U+9FA5 (explicit unicode escapes to satisfy lint "obscure range")
+const RE_IDENT_START = /[a-z_$\u4E00-\u9FA5]/i
+const RE_IDENT_BODY = /[\w$\u4E00-\u9FA5]/
+
+const SINGLE_OPS: Record<string, TokenType> = {
+    '+': 'PLUS',
+    '-': 'MINUS',
+    '*': 'STAR',
+    '/': 'SLASH',
+    '(': 'LPAREN',
+    ')': 'RPAREN',
+    ',': 'COMMA',
+}
+
+const tokenize = (input: string): IToken[] => {
+    const tokens: IToken[] = []
+    let i = 0
+    while (i < input.length) {
+        const c = input[i]!
+        if (RE_WS.test(c)) {
+            i++
+            continue
+        }
+        // Number (including decimal / scientific notation)
+        if (RE_DIGIT.test(c) || (c === '.' && RE_DIGIT.test(input[i + 1] || ''))) {
+            const start = i
+            while (i < input.length && RE_NUM_BODY.test(input[i]!)) i++
+            if (input[i] === 'e' || input[i] === 'E') {
+                i++
+                if (input[i] === '+' || input[i] === '-') i++
+                while (i < input.length && RE_DIGIT.test(input[i]!)) i++
+            }
+            tokens.push({ type: 'NUMBER', value: input.slice(start, i), pos: start })
+            // Trailing unit: lone % ⇒ UNIT token (exclude %% which is a format token)
+            if (input[i] === '%' && input[i + 1] !== '%') {
+                tokens.push({ type: 'UNIT', value: '%', pos: i })
+                i++
+            }
+            continue
+        }
+        // Identifier (math function names such as max / min / clamp)
+        if (RE_IDENT_START.test(c)) {
+            const start = i
+            i++
+            while (i < input.length && RE_IDENT_BODY.test(input[i]!)) i++
+            tokens.push({ type: 'IDENT', value: input.slice(start, i), pos: start })
+            continue
+        }
+        // Single-character operators
+        if (c in SINGLE_OPS) {
+            tokens.push({ type: SINGLE_OPS[c]!, value: c, pos: i })
+            i++
+            continue
+        }
+        throw new Error(`Illegal character at position ${i}: "${c}"`)
+    }
+    tokens.push({ type: 'EOF', value: '', pos: input.length })
+    return tokens
+}
+
+// ───── Evaluation context ─────
+/** Evaluation context for {@link evaluate} */
+export interface IEvalContext {
+    /** Unit mode: when `true`, `%` is treated as a unit marker rather than division by 100 */
+    unit: boolean
+    /** Maximum decimal places to retain in division */
+    precision: number
+    /** When an array is provided, evaluation steps are recorded into it (used by `_debug`) */
+    trace?: string[]
+}
+
+// ───── Built-in math functions (all use BigInt precision primitives for exact results) ─────
+/** Floor (toward -∞, same as Math.floor) */
+const mathFloor = (x: string): string => {
+    const t = truncate(x, 0)
+    return (cmp(x, '0') < 0 && cmp(x, t) !== 0) ? sub(t, '1') : t
+}
+/** Ceiling (toward +∞, same as Math.ceil) */
+const mathCeil = (x: string): string => {
+    const t = truncate(x, 0)
+    return (cmp(x, '0') > 0 && cmp(x, t) !== 0) ? add(t, '1') : t
+}
+/** Sign: -1 / 0 / 1 */
+const mathSign = (x: string): string => {
+    const c = cmp(x, '0')
+    return c > 0 ? '1' : c < 0 ? '-1' : '0'
+}
+/** Integer exponentiation (exponent must be an integer; negative exponents use division) */
+const mathPow = (base: string, expStr: string, precision: number): string => {
+    const e = Number(expStr)
+    if (!Number.isInteger(e)) throw new Error(`pow() exponent must be an integer: "${expStr}"`)
+    let r = '1'
+    for (let i = 0; i < Math.abs(e); i++) r = mul(r, base)
+    return e < 0 ? div('1', r, precision) : r
+}
+/** Modulo (remainder has the same sign as the dividend, same as JS %) */
+const mathMod = (a: string, b: string, precision: number): string => {
+    if (cmp(b, '0') === 0) throw new Error('mod division by zero')
+    const q = truncate(div(a, b, precision), 0) // truncate-toward-zero quotient
+    return sub(a, mul(q, b))
+}
+/** Pick a value from args by comparison (used for min / max) */
+const pickBy = (name: string, args: string[], keep: (c: number) => boolean): string => {
+    if (args.length === 0) throw new Error(`${name}() requires at least 1 argument`)
+    let r = args[0]!
+    for (let i = 1; i < args.length; i++) if (keep(cmp(args[i]!, r))) r = args[i]!
+    return r
+}
+
+// Fixed arity for each function (min/max are variadic and not in this table)
+const FN_ARITY: Record<string, number> = {
+    abs: 1,
+    sign: 1,
+    floor: 1,
+    ceil: 1,
+    round: 1,
+    trunc: 1,
+    pow: 2,
+    mod: 2,
+    clamp: 3,
+}
+
+/** Built-in functions (available inside expressions) */
+const applyFn = (name: string, args: string[], precision: number): string => {
+    const arity = FN_ARITY[name]
+    if (arity !== undefined && args.length !== arity) {
+        throw new Error(`${name}() expects ${arity} argument(s), got ${args.length}`)
+    }
+    switch (name) {
+        case 'abs':
+            return abs(args[0]!)
+        case 'sign':
+            return mathSign(args[0]!)
+        case 'floor':
+            return mathFloor(args[0]!)
+        case 'ceil':
+            return mathCeil(args[0]!)
+        case 'round':
+            return mathFloor(add(args[0]!, '0.5')) // same as Math.round (half rounds toward +∞)
+        case 'trunc':
+            return truncate(args[0]!, 0)
+        case 'pow':
+            return mathPow(args[0]!, args[1]!, precision)
+        case 'mod':
+            return mathMod(args[0]!, args[1]!, precision)
+        case 'min':
+            return pickBy('min', args, c => c < 0)
+        case 'max':
+            return pickBy('max', args, c => c > 0)
+        case 'clamp': {
+            const [x, lo, hi] = args as [string, string, string]
+            if (cmp(x, lo) < 0) return lo
+            if (cmp(x, hi) > 0) return hi
+            return x
+        }
+        default:
+            throw new Error(`Unknown function: "${name}()"`)
+    }
+}
+
+// ───── Parser + evaluator ─────
+class Parser {
+    private tokens: IToken[]
+    private pos = 0
+
+    constructor(input: string, private ctx: IEvalContext) {
+        this.tokens = tokenize(input)
+    }
+
+    private peek(): IToken { return this.tokens[this.pos]! }
+    private consume(): IToken { return this.tokens[this.pos++]! }
+    private match(...types: TokenType[]): IToken | null {
+        if (types.includes(this.peek().type)) return this.consume()
+        return null
+    }
+
+    private expect(type: TokenType): IToken {
+        const t = this.peek()
+        if (t.type !== type) throw new Error(`Expected ${type} at position ${t.pos}, got ${t.type}("${t.value}")`)
+        return this.consume()
+    }
+
+    private step(line: string): void {
+        if (this.ctx.trace) this.ctx.trace.push(line)
+    }
+
+    public parse(): string {
+        const v = this.addSub()
+        if (this.peek().type !== 'EOF') {
+            const t = this.peek()
+            throw new Error(`Unexpected token "${t.value}" at position ${t.pos} — expression not fully parsed`)
+        }
+        return v
+    }
+
+    private addSub(): string {
+        let left = this.mulDiv()
+        while (true) {
+            const op = this.match('PLUS', 'MINUS')
+            if (!op) break
+            const right = this.mulDiv()
+            const prev = left
+            left = op.type === 'PLUS' ? add(left, right) : sub(left, right)
+            this.step(`${prev} ${op.value} ${right} = ${left}`)
+        }
+        return left
+    }
+
+    private mulDiv(): string {
+        let left = this.unary()
+        while (true) {
+            const op = this.match('STAR', 'SLASH')
+            if (!op) break
+            const right = this.unary()
+            const prev = left
+            left = op.type === 'STAR' ? mul(left, right) : div(left, right, this.ctx.precision)
+            this.step(`${prev} ${op.value} ${right} = ${left}`)
+        }
+        return left
+    }
+
+    private unary(): string {
+        if (this.match('PLUS')) return this.unary()
+        if (this.match('MINUS')) return neg(this.unary())
+        return this.primary()
+    }
+
+    private primary(): string {
+        const t = this.peek()
+        if (t.type === 'NUMBER') {
+            this.consume()
+            const val = t.value
+            if (this.peek().type === 'UNIT') {
+                const u = this.consume()
+                if (u.value === '%') {
+                    // _unit=true ⇒ % is a unit marker; value is kept as-is (output layer appends %)
+                    // _unit=false ⇒ % means divide by 100
+                    if (this.ctx.unit) return val
+                    return div(val, '100', this.ctx.precision)
+                }
+            }
+            return val
+        }
+        if (t.type === 'IDENT') {
+            this.consume()
+            // Identifiers can only be math function names (followed by parentheses); variables are not supported — use template interpolation
+            if (this.peek().type === 'LPAREN') return this.callFn(t.value)
+            throw new Error(`Unknown identifier: "${t.value}" (calc supports arithmetic and math functions only; use template interpolation for values)`)
+        }
+        if (t.type === 'LPAREN') {
+            this.consume()
+            const v = this.addSub()
+            this.expect('RPAREN')
+            return v
+        }
+        throw new Error(`Unexpected token at position ${t.pos}: ${t.type}("${t.value}")`)
+    }
+
+    private callFn(name: string): string {
+        this.expect('LPAREN')
+        const args: string[] = []
+        if (this.peek().type !== 'RPAREN') {
+            args.push(this.addSub())
+            while (this.match('COMMA')) args.push(this.addSub())
+        }
+        this.expect('RPAREN')
+        const r = applyFn(name, args, this.ctx.precision)
+        this.step(`${name}(${args.join(', ')}) = ${r}`)
+        return r
+    }
+}
+
+/**
+ * Parse and evaluate an expression (the pure arithmetic part, without any format pipeline).
+ *
+ * Most callers should use {@link calc}; this is the low-level evaluator for cases where
+ * direct control over the evaluation context is needed.
+ *
+ * @param expr Pure expression string (no format pipe)
+ * @param ctx Evaluation context: unit mode flag and division precision
+ * @returns Canonical string representation of the evaluated result
+ * @throws Throws on lexical or syntax errors
+ * @example
+ * evaluate('1 + 2', { unit: false, precision: 50 }) // '3'
+ */
+export const evaluate = (expr: string, ctx: IEvalContext): string => {
+    return new Parser(expr, ctx).parse()
+}