@wzo/calc 0.0.1

package/dist/index.d.mts

@@ -0,0 +1,449 @@
+//#region src/utils/format.d.ts
+/**
+ * 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).
+ */
+type Rounding = 'truncate' | 'trunc' | 'halfUp' | 'round' | 'banker' | 'halfEven' | 'ceil';
+/**
+ * Format options object — passed to {@link fmt} / `calc`'s `_fmt` / chaining terminators.
+ * Equivalent to a format token string but with full type hints.
+ */
+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;
+}
+/** Options for {@link fmt}: formatting fields (see {@link IFormat}) plus `_`-prefixed control options */
+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;
+}
+declare const fmt: (value: string | number | bigint, options?: IFmtOptions) => string | number;
+//#endregion
+//#region src/utils/config.d.ts
+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;
+}
+/** Per-call precision override: optional last argument accepted by `div` / `divStr` / `chainDiv` / `calcAvg`. */
+interface IPrecisionOption {
+  /** Division precision for this call, overrides the global `_precision` (does not affect the global config). */
+  _precision?: number;
+}
+/**
+ * Partially updates the global configuration (only the provided fields are overwritten).
+ *
+ * @param patch Configuration fields to update
+ * @example
+ * setConfig({ _precision: 10, _fmt: { decimals: 2 } })
+ */
+declare const setConfig: (patch: Partial<IGlobalConfig>) => void;
+/**
+ * Resets the global configuration to its default values.
+ *
+ * @example
+ * resetConfig()
+ */
+declare const resetConfig: () => void;
+/**
+ * Returns the current global configuration object (by reference — do not mutate directly; use {@link setConfig}).
+ *
+ * @returns The current {@link IGlobalConfig}
+ */
+declare const getConfig: () => IGlobalConfig;
+//#endregion
+//#region src/utils/aggregate.d.ts
+type Val$2 = string | number | bigint;
+type Item = Record<string, Val$2 | null | undefined>;
+/**
+ * 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'
+ */
+declare const calcSum: (keyOrArr: string | Val$2[], list?: Item[]) => string;
+/**
+ * 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'
+ */
+declare function calcAvg(arr: Val$2[], opt?: IPrecisionOption): string;
+declare function calcAvg(key: string, list: Item[], opt?: IPrecisionOption): string;
+/**
+ * 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'
+ */
+declare const calcMax: (keyOrArr: string | Val$2[], list?: Item[]) => string;
+/**
+ * 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'
+ */
+declare const calcMin: (keyOrArr: string | Val$2[], list?: Item[]) => string;
+//#endregion
+//#region src/utils/calc.d.ts
+/** Control options for {@link calc} (all prefixed with `_`; variables are not supported — embed values via template interpolation) */
+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` */
+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;
+}
+/**
+ * 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'
+ */
+declare const calc: (expr: string, options?: ICalcOptions) => string | number;
+//#endregion
+//#region src/utils/chain.d.ts
+type Val$1 = string | number | bigint;
+/**
+ * A chaining computation object. Every arithmetic method returns itself for further chaining;
+ * calling it as a function terminates the chain and returns the result.
+ */
+interface IChain {
+  /** Continues accumulating additions; returns itself for chaining. */
+  add: (...args: Val$1[]) => IChain;
+  /** Continues accumulating subtractions; returns itself. */
+  sub: (...args: Val$1[]) => IChain;
+  /** Continues accumulating multiplications; returns itself. */
+  mul: (...args: Val$1[]) => IChain;
+  /** Continues accumulating divisions (uses the instance's `_precision`); returns itself. */
+  div: (...args: Val$1[]) => 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;
+}
+/**
+ * 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'
+ */
+declare const chainAdd: (...args: Val$1[]) => IChain;
+/**
+ * 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'
+ */
+declare const chainSub: (...args: Val$1[]) => IChain;
+/**
+ * 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'
+ */
+declare const chainMul: (...args: Val$1[]) => IChain;
+/**
+ * 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'
+ */
+declare function chainDiv(...args: Val$1[]): IChain;
+declare function chainDiv(...args: [...Val$1[], IPrecisionOption]): IChain;
+//#endregion
+//#region src/utils/precision.d.ts
+/** Internal decimal representation: a number = `sign * digits / 10^exp` */
+interface IDecimal {
+  /** Sign: `1` for positive, `-1` for negative. */
+  sign: 1 | -1;
+  /** Significant digits as a non-negative integer (decimal point removed). */
+  digits: bigint;
+  /** Number of decimal places (negative exponent of `10`). */
+  exp: number;
+}
+/**
+ * Parses a string, number, or bigint into the internal {@link IDecimal} representation.
+ *
+ * Supports standard decimals (`"1.23"`, `-0.5`) and scientific notation (`"1.2e-3"`).
+ *
+ * @param input Value to parse, e.g. `"3.14"`, `42`, `-1n`, `"1e10"`
+ * @returns Parsed {@link IDecimal} (`digits` is always >= 0; sign is carried by `sign`)
+ * @throws When the string is not a valid number
+ * @example
+ * parse('1.23') // { sign: 1, digits: 123n, exp: 2 }
+ * parse('-5')   // { sign: -1, digits: 5n, exp: 0 }
+ */
+declare const parse: (input: string | number | bigint) => IDecimal;
+/**
+ * High-precision division `a / b`, result rounded to `precision` decimal places (half-up).
+ *
+ * @param a Dividend
+ * @param b Divisor
+ * @param precision Maximum decimal places to retain, defaults to `50`
+ * @returns Canonical string of the quotient
+ * @throws When the divisor is zero
+ * @example
+ * div('1', '3')      // '0.333...' (up to 50 places)
+ * div('1', '3', 4)   // '0.3333'
+ */
+declare const div$1: (a: string | number | bigint, b: string | number | bigint, precision?: number) => string;
+/**
+ * Compares two numbers numerically.
+ *
+ * @param a Left operand
+ * @param b Right operand
+ * @returns `1` if `a > b`, `-1` if `a < b`, `0` if equal
+ * @example
+ * cmp('0.1', '0.2') // -1
+ * cmp('2', '2.0')   // 0
+ */
+declare const cmp: (a: string | number | bigint, b: string | number | bigint) => number;
+/**
+ * Returns the negation `-a`.
+ *
+ * @param a Input value
+ * @returns Canonical string of the negation (`0` always returns `'0'`)
+ * @example
+ * neg('1.5')  // '-1.5'
+ * neg('-2')   // '2'
+ */
+declare const neg: (a: string | number | bigint) => string;
+/**
+ * Returns the absolute value `|a|`.
+ *
+ * @param a Input value
+ * @returns Canonical string of the absolute value
+ * @example
+ * abs('-3.14') // '3.14'
+ */
+declare const abs: (a: string | number | bigint) => string;
+/**
+ * Truncates to N decimal places by discarding excess digits — **no rounding**.
+ *
+ * @param a Input value
+ * @param decimals Number of decimal places to keep
+ * @returns Canonical string after truncation
+ * @example
+ * truncate('1.2349', 2) // '1.23'
+ * truncate('1.99', 0)   // '1'
+ */
+declare const truncate: (a: string | number | bigint, decimals: number) => string;
+/**
+ * Rounds to N decimal places using half-up rounding (rounds up when digit `>= 0.5`).
+ *
+ * @param a Input value
+ * @param decimals Number of decimal places to keep
+ * @returns Canonical string after rounding
+ * @example
+ * roundHalfUp('1.235', 2) // '1.24'
+ * roundHalfUp('1.234', 2) // '1.23'
+ */
+declare const roundHalfUp: (a: string | number | bigint, decimals: number) => string;
+/**
+ * Rounds away from zero to N decimal places (rounds up whenever there is any remainder).
+ *
+ * @param a Input value
+ * @param decimals Number of decimal places to keep
+ * @returns Canonical string after rounding
+ * @example
+ * roundCeil('1.231', 2)  // '1.24'
+ * roundCeil('-1.231', 2) // '-1.24'
+ */
+declare const roundCeil: (a: string | number | bigint, decimals: number) => string;
+/**
+ * Banker's rounding (round half to even): when the discarded portion is exactly `0.5`,
+ * rounds to the nearest even digit.
+ *
+ * @param a Input value
+ * @param decimals Number of decimal places to keep
+ * @returns Canonical string after rounding
+ * @example
+ * roundBanker('0.5', 0)  // '0'
+ * roundBanker('1.5', 0)  // '2'
+ * roundBanker('2.5', 0)  // '2'
+ */
+declare const roundBanker: (a: string | number | bigint, decimals: number) => string;
+//#endregion
+//#region src/utils/standalone.d.ts
+type Val = string | number | bigint;
+/** Division using the precision from the given config (shared by the default {@link div} export and per-call precision entry points). */
+
+/**
+ * High-precision addition, result converted to `number` (convenient for interop with native numbers).
+ *
+ * @param args Any number of addends, accumulated left to right
+ * @returns Sum (`number`)
+ * @example
+ * add(0.1, 0.2)       // 0.3
+ * add(1, 2, 3, 4)     // 10
+ */
+declare const add: (...args: Val[]) => number;
+/**
+ * High-precision subtraction, result as `number`: `args[0] - args[1] - args[2] ...`.
+ *
+ * @param args Minuend followed by subtrahends
+ * @returns Difference (`number`)
+ * @example
+ * sub(0.3, 0.1) // 0.2
+ */
+declare const sub: (...args: Val[]) => number;
+/**
+ * High-precision multiplication, result as `number`, factors multiplied left to right.
+ *
+ * @param args Any number of factors
+ * @returns Product (`number`)
+ * @example
+ * mul(0.1, 0.2) // 0.02
+ */
+declare const mul: (...args: Val[]) => number;
+/**
+ * High-precision division, result as `number`: `args[0] / args[1] / args[2] ...`.
+ *
+ * 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).
+ *
+ * @param args Dividend and divisors, with an optional {@link IPrecisionOption} at the end
+ * @returns Quotient (`number`)
+ * @example
+ * div(1, 3)                      // 0.333... (global precision)
+ * div(100, 3, { _precision: 5 }) // 33.33333
+ */
+declare function div(...args: Val[]): number;
+declare function div(...args: [...Val[], IPrecisionOption]): number;
+/**
+ * High-precision addition, result returned as `string` (no precision loss; suitable for monetary values).
+ *
+ * @param args Any number of addends
+ * @returns Sum (`string`)
+ * @example
+ * addStr('0.1', '0.2') // '0.3'
+ */
+declare const addStr: (...args: Val[]) => string;
+/**
+ * High-precision subtraction, result as `string`: `args[0] - args[1] - ...`.
+ *
+ * @param args Minuend followed by subtrahends
+ * @returns Difference (`string`)
+ * @example
+ * subStr('0.3', '0.1') // '0.2'
+ */
+declare const subStr: (...args: Val[]) => string;
+/**
+ * High-precision multiplication, result as `string`, factors multiplied left to right.
+ *
+ * @param args Any number of factors
+ * @returns Product (`string`)
+ * @example
+ * mulStr('0.1', '0.2') // '0.02'
+ */
+declare const mulStr: (...args: Val[]) => string;
+/**
+ * High-precision division, result as `string`: `args[0] / args[1] / ...`.
+ *
+ * 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).
+ *
+ * @param args Dividend and divisors, with an optional {@link IPrecisionOption} at the end
+ * @returns Quotient (`string`)
+ * @example
+ * divStr('1', '3')                      // '0.333...' (global precision)
+ * divStr('100', '3', { _precision: 5 }) // '33.33333'
+ */
+declare function divStr(...args: Val[]): string;
+declare function divStr(...args: [...Val[], IPrecisionOption]): string;
+//#endregion
+export { type ICalcOptions, type IChain, type IDebugInfo, type IDecimal, type IFmtOptions, type IFormat, type IGlobalConfig, type IPrecisionOption, type Rounding, abs, add, addStr, calc, calcAvg, calcMax, calcMin, calcSum, chainAdd, chainDiv, chainMul, chainSub, cmp, div, divStr, fmt, getConfig, mul, mulStr, neg, parse, div$1 as rawDiv, resetConfig, roundBanker, roundCeil, roundHalfUp, setConfig, sub, subStr, truncate };