@wzo/calc 0.0.1

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@wzo/calc",
+  "type": "module",
+  "version": "0.0.1",
+  "description": "Precision math + number formatting — zero runtime dependencies, BigInt internally",
+  "author": "nowo",
+  "license": "MIT",
+  "homepage": "https://nowo.github.io/calc",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nowo/calc.git",
+    "directory": "packages/main"
+  },
+  "bugs": "https://github.com/nowo/calc/issues",
+  "keywords": [
+    "calc",
+    "precision",
+    "decimal",
+    "bignumber",
+    "format"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "README.zh.md",
+    "dist",
+    "src"
+  ],
+  "engines": {
+    "node": ">=16.6"
+  },
+  "devDependencies": {
+    "a-calc": "^3.0.0",
+    "changelogen": "^0.6.2",
+    "decimal.js": "^10.6.0",
+    "mathjs": "^15.2.0",
+    "tsdown": "^0.18.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "bench": "vitest bench --run",
+    "release": "changelogen --release --push"
+  }
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+// @wzo/calc — precision math + number formatting
+// Zero runtime dependencies; all precision arithmetic uses BigInt internally
+
+export { calcAvg, calcMax, calcMin, calcSum } from './utils/aggregate'
+export { calc, fmt } from './utils/calc'
+
+export type { ICalcOptions, IDebugInfo } from './utils/calc'
+export { chainAdd, chainDiv, chainMul, chainSub } from './utils/chain'
+
+export type { IChain } from './utils/chain'
+export { getConfig, resetConfig, setConfig } from './utils/config'
+
+export type { IGlobalConfig, IPrecisionOption } from './utils/config'
+
+export type { IFmtOptions, IFormat, Rounding } from './utils/format'
+
+// Advanced usage: direct access to precision primitives
+export {
+    abs,
+    cmp,
+    neg,
+    parse,
+    div as rawDiv, // division with explicit precision parameter (for add/sub/mul use addStr/subStr/mulStr)
+    roundBanker,
+    roundCeil,
+    roundHalfUp,
+    truncate,
+} from './utils/precision'
+
+export type { IDecimal } from './utils/precision'
+export { add, addStr, div, divStr, mul, mulStr, sub, subStr } from './utils/standalone'

package/src/utils/aggregate.ts

@@ -0,0 +1,109 @@
+// Aggregation: calcSum / calcAvg / calcMax / calcMin
+// Usage: calcSum("price", [{ price: 10 }, { price: 20 }]) → "30"
+//        calcSum([1, 2, 3]) → "6"  (direct array form)
+
+import type { IGlobalConfig, IPrecisionOption } from './config'
+import { configWithPrecision } from './config'
+import { add as addStr, cmp, div as divStr } from './precision'
+
+type Val = string | number | bigint
+// Values may be null / undefined: backends often return null/undefined values; pickValues skips them (the type reflects this design)
+type Item = Record<string, Val | null | undefined>
+
+const pickValues = (keyOrArr: string | Val[], list?: Item[]): string[] => {
+    let raw: Array<Val | null | undefined>
+    if (Array.isArray(keyOrArr)) {
+        raw = keyOrArr
+    } else {
+        if (!list) throw new Error('list is required when keyOrArr is a field name')
+        raw = list.map(item => item[keyOrArr])
+    }
+    // Skip null / undefined (backends often return empty values) to avoid parse errors from String(null)
+    return raw.filter(v => v != null).map(v => String(v))
+}
+
+/** Internal sum core — invalid values throw and propagate to the caller. */
+const sumOf = (values: string[]): string => {
+    if (values.length === 0) return '0'
+    let sum = values[0]!
+    for (let i = 1; i < values.length; i++) sum = addStr(sum, values[i]!)
+    return sum
+}
+
+/**
+ * Computes the sum. Accepts two call forms: a direct value array, or a field name with an array of objects.
+ *
+ * @param keyOrArr Value array (`[1, 2, 3]`) or the field name to sum (`'price'`)
+ * @param list Array of objects, required when the first argument is a field name
+ * @returns Total sum (`string`, high precision)
+ * @example
+ * calcSum([1, 2, 3])                              // '6'
+ * calcSum('price', [{ price: 10 }, { price: 20 }]) // '30'
+ */
+export const calcSum = (keyOrArr: string | Val[], list?: Item[]): string => sumOf(pickValues(keyOrArr, list))
+
+/** Computes the average with the given config precision (shared by the default {@link calcAvg} export and per-call precision entry points). */
+export const calcAvgWith = (cfg: IGlobalConfig, keyOrArr: string | Val[], list?: Item[]): string => {
+    const values = pickValues(keyOrArr, list)
+    if (values.length === 0) return '0'
+    return divStr(sumOf(values), String(values.length), cfg._precision)
+}
+
+/**
+ * Computes the average (sum / count). Returns `'0'` for an empty collection.
+ *
+ * Precision defaults to the global `_precision`; pass `{ _precision }` as the **last** argument
+ * to override it for this call only (does not affect the global config).
+ *
+ * The first argument is either a value array (`[1,2,3]`) or a field name (`'price'`
+ * used together with an array of objects as the second argument).
+ *
+ * @returns Average value (`string`)
+ * @example
+ * calcAvg([1, 2, 3])                               // '2'
+ * calcAvg('score', [{ score: 80 }, { score: 90 }]) // '85'
+ * calcAvg([10, 20, 25], { _precision: 2 })         // '18.33'
+ */
+export function calcAvg(arr: Val[], opt?: IPrecisionOption): string
+export function calcAvg(key: string, list: Item[], opt?: IPrecisionOption): string
+export function calcAvg(keyOrArr: string | Val[], listOrOpt?: Item[] | IPrecisionOption, opt?: IPrecisionOption): string {
+    // Array form: second argument is opt; field-name form: second argument is list, third is opt
+    const isFieldForm = Array.isArray(listOrOpt)
+    const list = isFieldForm ? listOrOpt : undefined
+    const o = isFieldForm ? opt : listOrOpt
+    return calcAvgWith(configWithPrecision(o), keyOrArr, list)
+}
+
+/**
+ * Returns the maximum value (numeric comparison, not lexicographic).
+ *
+ * @param keyOrArr Value array or field name
+ * @param list Array of objects, required when the first argument is a field name
+ * @returns Maximum value (`string`); returns `'0'` for an empty collection
+ * @example
+ * calcMax([3, 10, 2]) // '10'
+ */
+export const calcMax = (keyOrArr: string | Val[], list?: Item[]): string => {
+    const values = pickValues(keyOrArr, list)
+    if (values.length === 0) return '0'
+    let max = values[0]!
+    for (let i = 1; i < values.length; i++) if (cmp(values[i]!, max) > 0) max = values[i]!
+    return max
+}
+
+/**
+ * Returns the minimum value (numeric comparison).
+ *
+ * @param keyOrArr Value array or field name
+ * @param list Array of objects, required when the first argument is a field name
+ * @returns Minimum value (`string`); returns `'0'` for an empty collection
+ * @example
+ * calcMin([3, 10, 2]) // '2'
+ */
+export const calcMin = (keyOrArr: string | Val[], list?: Item[]): string => {
+    const values = pickValues(keyOrArr, list)
+    if (values.length === 0) return '0'
+    let min = values[0]!
+    for (let i = 1; i < values.length; i++) if (cmp(values[i]!, min) < 0) min = values[i]!
+    return min
+}

package/src/utils/calc.ts

@@ -0,0 +1,100 @@
+// Entry point calc(): arithmetic expression evaluation → (optional) formatting
+
+import type { IGlobalConfig } from './config'
+import type { IFormat } from './format'
+import type { IEvalContext } from './parser'
+import { getConfig } from './config'
+import { formatValue, normalizeFormat } from './format'
+import { evaluate } from './parser'
+
+/** Control options for {@link calc} (all prefixed with `_`; variables are not supported — embed values via template interpolation) */
+export interface ICalcOptions {
+    /** true ⇒ enable unit mode (% is treated as a unit marker rather than division by 100; the result retains the % suffix) */
+    _unit?: boolean
+    /** Explicit format: an {@link IFormat} options object */
+    _fmt?: IFormat
+    /** Division precision (defaults to the global `_precision`) */
+    _precision?: number
+    /**
+     * Step-by-step evaluation debug:
+     * - `true` ⇒ prints to console
+     * - pass a function ⇒ receives {@link IDebugInfo} via callback, no console output
+     */
+    _debug?: boolean | ((info: IDebugInfo) => void)
+}
+
+/** Evaluation info collected by `_debug` */
+export interface IDebugInfo {
+    /** The original expression */
+    expr: string
+    /** Step-by-step evaluation trace (one entry per step) */
+    steps: string[]
+    /** Raw result before formatting */
+    value: string
+    /** Final returned value */
+    result: string | number
+}
+
+const RE_HAS_PERCENT = /%/
+
+const emitDebug = (info: IDebugInfo, debug: true | ((info: IDebugInfo) => void)): void => {
+    if (typeof debug === 'function') {
+        debug(info)
+        return
+    }
+    // eslint-disable-next-line no-console
+    console.log(
+        `[calc] ${info.expr}\n${
+            info.steps.length ? `${info.steps.map(s => `  · ${s}`).join('\n')}\n` : ''
+        }  = ${info.result}`,
+    )
+}
+
+/** Evaluate with an explicit config (the default export {@link calc} delegates to this). */
+export function calcWith(cfg: IGlobalConfig, expr: string, options: ICalcOptions = {}): string | number {
+    const steps = options._debug ? [] as string[] : undefined
+    const ctx: IEvalContext = {
+        unit: !!options._unit,
+        precision: options._precision ?? cfg._precision,
+        trace: steps,
+    }
+    const value = evaluate(expr, ctx)
+
+    // Unit mode: if the expression contains %, append % to the result (only when no explicit format is set)
+    const exprHasPercent = options._unit && RE_HAS_PERCENT.test(expr)
+
+    const fmtSpec = options._fmt || cfg._fmt
+    const result = !fmtSpec
+        ? (exprHasPercent ? `${value}%` : value)
+        : formatValue(value, normalizeFormat(fmtSpec))
+
+    if (options._debug) emitDebug({ expr, steps: steps!, value, result }, options._debug)
+    return result
+}
+
+/**
+ * Main entry point: evaluates an arithmetic expression string and optionally formats the output.
+ *
+ * Expressions are pure arithmetic: the four basic operations, parentheses, and math functions
+ * (`max`/`min`/`clamp`…). **Variables are not supported** — embed values directly in the
+ * expression via template interpolation: `` calc(`${price} * ${qty}`) ``.
+ * Formatting is specified via `options._fmt` (an {@link IFormat} object).
+ *
+ * `calc` is designed for **computation**: on error (invalid expression, etc.) it **throws
+ * directly** and the caller is responsible for handling it.
+ * For **display** scenarios that need a fallback on error, use {@link fmt} instead
+ * (same API and supports arithmetic, but returns `_error` on failure rather than throwing).
+ *
+ * @param expr Arithmetic expression, e.g. `'1 + 2 * 3'`, `'(1 + 2) / 3'`
+ * @param options Control options (see {@link ICalcOptions})
+ * @returns Computation result (`string`; `number` when `_fmt.output` is `'number'`)
+ * @throws Throws when the expression is invalid
+ * @example
+ * calc('1 + 2 * 3')                        // '7'
+ * calc(`${price} * ${qty}`)                // use template interpolation instead of variables
+ * calc('1 + 2', { _fmt: { decimals: 2 } }) // '3.00'
+ */
+export const calc = (expr: string, options: ICalcOptions = {}): string | number => calcWith(getConfig(), expr, options)
+
+/** Direct formatting */
+export { fmt } from './format'

package/src/utils/chain.ts

@@ -0,0 +1,127 @@
+// Chaining API: chainAdd/chainSub/chainMul/chainDiv → returns an object supporting further .add().sub().mul().div() calls
+// Terminate: call with () or (formatStr) to obtain the final string/number result
+// Errors (invalid arguments, etc.) are thrown directly and must be handled by the caller
+
+import type { IGlobalConfig, IPrecisionOption } from './config'
+import type { IFormat } from './format'
+import { configWithPrecision, getConfig } from './config'
+import { formatValue, normalizeFormat } from './format'
+import { add, div, mul, sub } from './precision'
+
+type Val = string | number | bigint
+
+/** Extracts a per-call precision option from the end of a variadic argument list (last element is an object ⇒ treated as {@link IPrecisionOption}). */
+const splitPrecision = (args: Array<Val | IPrecisionOption>): [Val[], IPrecisionOption?] => {
+    const last = args.at(-1)
+    if (last != null && typeof last === 'object') {
+        return [args.slice(0, -1) as Val[], last as IPrecisionOption]
+    }
+    return [args as Val[], undefined]
+}
+
+/**
+ * A chaining computation object. Every arithmetic method returns itself for further chaining;
+ * calling it as a function terminates the chain and returns the result.
+ */
+export interface IChain {
+    /** Continues accumulating additions; returns itself for chaining. */
+    add: (...args: Val[]) => IChain
+    /** Continues accumulating subtractions; returns itself. */
+    sub: (...args: Val[]) => IChain
+    /** Continues accumulating multiplications; returns itself. */
+    mul: (...args: Val[]) => IChain
+    /** Continues accumulating divisions (uses the instance's `_precision`); returns itself. */
+    div: (...args: Val[]) => IChain
+    /**
+     * Terminates the chain and retrieves the result: no argument ⇒ returns the current value (`string`);
+     * pass an {@link IFormat} object ⇒ returns `string | number` according to the formatting rules.
+     */
+    (format?: IFormat): string | number
+}
+
+const makeChain = (cfg: IGlobalConfig, initial: string): IChain => {
+    let value = initial
+    const fn = ((format?: IFormat): string | number => {
+        if (!format) return value
+        return formatValue(value, normalizeFormat(format))
+    }) as IChain
+
+    fn.add = (...args: Val[]) => {
+        for (const a of args) value = add(value, a)
+        return fn
+    }
+    fn.sub = (...args: Val[]) => {
+        for (const a of args) value = sub(value, a)
+        return fn
+    }
+    fn.mul = (...args: Val[]) => {
+        for (const a of args) value = mul(value, a)
+        return fn
+    }
+    fn.div = (...args: Val[]) => {
+        for (const a of args) value = div(value, a, cfg._precision)
+        return fn
+    }
+    return fn
+}
+
+const reduceWith = (op: (a: string, b: Val) => string, args: Val[]): string => {
+    if (args.length === 0) return '0'
+    let r = String(args[0])
+    for (let i = 1; i < args.length; i++) r = op(r, args[i]!)
+    return r
+}
+
+// ── Internal implementations that accept a config (shared by default exports and per-call precision entry points) ──
+export const chainAddWith = (cfg: IGlobalConfig, ...args: Val[]): IChain => makeChain(cfg, reduceWith(add, args))
+export const chainSubWith = (cfg: IGlobalConfig, ...args: Val[]): IChain => makeChain(cfg, reduceWith(sub, args))
+export const chainMulWith = (cfg: IGlobalConfig, ...args: Val[]): IChain => makeChain(cfg, reduceWith(mul, args))
+export const chainDivWith = (cfg: IGlobalConfig, ...args: Val[]): IChain => makeChain(cfg, reduceWith((a, b) => div(a, b, cfg._precision), args))
+
+/**
+ * Starts a chaining computation with addition (`a + b + c ...`).
+ *
+ * @param args Initial values to accumulate via addition
+ * @returns An {@link IChain} supporting further `.add().sub().mul().div()` calls
+ * @example
+ * chainAdd(1, 2).mul(3)()                // '9'
+ * chainAdd(1, 2).mul(3)({ decimals: 2 }) // '9.00'
+ */
+export const chainAdd = (...args: Val[]): IChain => chainAddWith(getConfig(), ...args)
+/**
+ * Starts a chaining computation with subtraction (`a - b - c ...`).
+ *
+ * @param args Initial minuend and subtrahends
+ * @returns An {@link IChain} supporting further chaining
+ * @example
+ * chainSub(10, 1, 2)() // '7'
+ */
+export const chainSub = (...args: Val[]): IChain => chainSubWith(getConfig(), ...args)
+/**
+ * Starts a chaining computation with multiplication (`a * b * c ...`).
+ *
+ * @param args Initial factors to multiply together
+ * @returns An {@link IChain} supporting further chaining
+ * @example
+ * chainMul(2, 3).add(4)() // '10'
+ */
+export const chainMul = (...args: Val[]): IChain => chainMulWith(getConfig(), ...args)
+/**
+ * Starts a chaining computation with division (`a / b / c ...`).
+ *
+ * Precision defaults to the global `_precision`; pass `{ _precision }` as the **last** argument
+ * to override the division precision for this chain (including subsequent `.div()` calls)
+ * without affecting the global config.
+ *
+ * @param args Initial dividend and divisors, with an optional {@link IPrecisionOption} at the end
+ * @returns An {@link IChain} supporting further chaining
+ * @example
+ * chainDiv(100, 4)()                    // '25'
+ * chainDiv(100, 3, { _precision: 5 })() // '33.33333'
+ */
+export function chainDiv(...args: Val[]): IChain
+export function chainDiv(...args: [...Val[], IPrecisionOption]): IChain
+export function chainDiv(...args: Array<Val | IPrecisionOption>): IChain {
+    const [values, opt] = splitPrecision(args)
+    return chainDivWith(configWithPrecision(opt), ...values)
+}

package/src/utils/config.ts

@@ -0,0 +1,59 @@
+// Global config: error fallback, default format, division precision
+
+import type { IFormat } from './format'
+
+export interface IGlobalConfig {
+    /** Fallback value on error: defaults to `'-'`; set to `0` to return `'0'` on error. */
+    _error: string | number
+    /** Global default format ({@link IFormat} object). */
+    _fmt: IFormat | undefined
+    /** Division precision (maximum decimal places). */
+    _precision: number
+}
+
+/** Default configuration values. */
+export const DEFAULT_CONFIG: IGlobalConfig = {
+    _error: '-',
+    _fmt: undefined,
+    _precision: 50,
+}
+
+/** Per-call precision override: optional last argument accepted by `div` / `divStr` / `chainDiv` / `calcAvg`. */
+export interface IPrecisionOption {
+    /** Division precision for this call, overrides the global `_precision` (does not affect the global config). */
+    _precision?: number
+}
+
+const config: IGlobalConfig = { ...DEFAULT_CONFIG }
+
+/**
+ * Partially updates the global configuration (only the provided fields are overwritten).
+ *
+ * @param patch Configuration fields to update
+ * @example
+ * setConfig({ _precision: 10, _fmt: { decimals: 2 } })
+ */
+export const setConfig = (patch: Partial<IGlobalConfig>): void => {
+    Object.assign(config, patch)
+}
+
+/**
+ * Resets the global configuration to its default values.
+ *
+ * @example
+ * resetConfig()
+ */
+export const resetConfig = (): void => {
+    Object.assign(config, DEFAULT_CONFIG)
+}
+
+/**
+ * Returns the current global configuration object (by reference — do not mutate directly; use {@link setConfig}).
+ *
+ * @returns The current {@link IGlobalConfig}
+ */
+export const getConfig = (): IGlobalConfig => config
+
+/** Returns the global config; if `_precision` is provided, returns a copy with that field overridden without mutating the global singleton. */
+export const configWithPrecision = (opt?: IPrecisionOption): IGlobalConfig =>
+    opt?._precision != null ? { ...config, _precision: opt._precision } : config