34:["$","title",null,{"children":"Achieving Fixed-Point Decimal Arithmetic in JavaScript | Michaël Guitton | Observable"}] 3c:T6f97,BigDecimal /* use `const [BigDecimal]` in REPL ツ */ = (function* ({ __EXPONENT_CAP__ = 10000, __SCALE__ = 18 } = {}) { const parseDecimal = /^([+-]?)(?=\d|[.]\d)(?:0*(0|[1-9]\d*))?([.](\d*?)0*)?(?:[eE]([+-]?\d+))?$/; /** * Places the decimal point according to a base-10 exponent. * * @param {string} wholePart The whole-number digits. * @param {string} fractPart The fractional digits. * @param {string | number} exponent The base-10 exponent. * @returns {[string, string]} The normalized whole and fractional parts. */ function normalizeDecimalParts(wholePart, fractPart, exponent) { const digits = wholePart + fractPart; const pointOffset = wholePart.length + Number(exponent); if (pointOffset <= 0) { return ["0", /* leading zeroes */ "0".repeat(-pointOffset) + digits]; } if (pointOffset >= digits.length) { return [ digits + /* trailing zeroes */ "0".repeat(pointOffset - digits.length), "" ]; } return [digits.slice(0, pointOffset), digits.slice(pointOffset)]; } /** * Fixed-point decimal backed by a scaled BigInt, using up to 18 fractional * digits by default. * * String inputs may use underscores as digit separators, provided each * underscore is between digits. Separators are removed before parsing. * * Scientific-notation exponents must be integers within the configured * exponent cap (10,000 by default). * * Values are rounded to the configured rounding mode when parsed or when an * operation requires rounding. The default mode is HALF_EVEN. Passing * `rounding: false` selects TOWARD_ZERO. * * This code is an adaptation of the Stack Overflow * {@link https://stackoverflow.com/a/66939244 original answer} by * {@link https://stackoverflow.com/users/1207193/trincot trincot}, and has * been substantially modified. * * The original answer is licensed under * {@link creativecommons.org/licenses/by-sa/4.0/ CC BY-SA 4.0}. * * This adaptation is distributed under CC BY-SA 4.0. * * @example * const amount = new BigDecimal("12.345", { rounding: false }); * console.log(amount.add("0.005").toString()); // "12.35" * * @example * const amount = new BigDecimal("1_234.56_78"); * console.log(amount.toString()); // "1234.5678" */ yield new Proxy( class BigDecimal { static #scale = Math.min(18, Math.max(2, __SCALE__ | 0)); // number of decimal places static #scaleFactor = 10n ** BigInt(this.#scale); static #semaphore = Symbol("BigDecimal"); // internal construction flag /** * IEEE 754 binary64 layout constants used internally by `numberValueExact()`. * * The method uses these values to decode a JavaScript `Number` into its * sign, significand, and binary exponent, then checks whether it exactly * represents this instance's fixed-point decimal value. These constants * describe the `Number` format; they do not set the decimal scale. * * @type {Readonly<{ * fractionBits: bigint, * exponentBits: bigint, * exponentBias: number, * totalBits: bigint, * fractionMask: bigint, * exponentMask: bigint * }>} */ static #Float64 = Object.freeze({ fractionBits: 52n, exponentBits: 11n, exponentBias: 1023, totalBits: 64n, fractionMask: (1n << 52n) - 1n, exponentMask: (1n << 11n) - 1n }); static RoundingMode = Object.freeze({ AWAY_FROM_ZERO: "AWAY_FROM_ZERO", HALF_AWAY_FROM_ZERO: "HALF_AWAY_FROM_ZERO", HALF_EVEN: "HALF_EVEN", TOWARD_NEGATIVE: "TOWARD_NEGATIVE", TOWARD_POSITIVE: "TOWARD_POSITIVE", TOWARD_ZERO: "TOWARD_ZERO" }); /** * Creates a BigDecimal from an integer already multiplied by the scale * factor. * * @param {bigint} n The scaled integer value. * @param {string} roundingMode The rounding mode for the new instance. * @returns {BigDecimal} The created decimal. * @private */ static #create = (n, roundingMode) => new this(n, { roundingMode, [this.#semaphore]: true }); /** * Divides two integers and rounds the quotient according to the selected * mode. HALF_AWAY_FROM_ZERO rounds exact ties away from zero. * * @param {bigint} dividend The dividend. * @param {bigint} divisor The divisor; it must not be zero. * @param {string} roundingMode The rounding mode to apply. * @returns {bigint} The rounded quotient. * @throws {RangeError} If the divisor is zero. * @private */ static #divide = (dividend, divisor, roundingMode) => { let quotient = dividend / divisor; const remainder = dividend % divisor; if (0n === remainder) { return quotient; } const isNegative = remainder < 0n !== divisor < 0n; const step = isNegative ? -1n : 1n; switch (roundingMode) { case this.RoundingMode.AWAY_FROM_ZERO: return quotient + step; case this.RoundingMode.HALF_AWAY_FROM_ZERO: case this.RoundingMode.HALF_EVEN: { const remainderMagnitude = remainder < 0n ? -remainder : remainder; const divisorMagnitude = divisor < 0n ? -divisor : divisor; const twiceRemainder = remainderMagnitude * 2n; if (twiceRemainder < divisorMagnitude) { return quotient; } if (twiceRemainder > divisorMagnitude) { return quotient + step; } // Exact tie. if (this.RoundingMode.HALF_AWAY_FROM_ZERO === roundingMode) { return quotient + step; } return 0n === quotient % 2n ? quotient : quotient + step; } case this.RoundingMode.TOWARD_NEGATIVE: return isNegative ? quotient - 1n : quotient; case this.RoundingMode.TOWARD_POSITIVE: return isNegative ? quotient : quotient + 1n; case this.RoundingMode.TOWARD_ZERO: default: // Unknown modes fall back to truncation toward zero. return quotient; } }; /** * Selects the greatest or smallest value from an iterable. * * @param {Iterable} values * Values to compare. * @param {{cmp?: (comparison: -1|0|1) => boolean}} [options] * Comparison predicate used to select the next value. Defaults to selecting * the greater value. * @returns {BigDecimal} The selected value, as a BigDecimal. * @throws {TypeError} If `values` is not iterable. * @throws {RangeError} If `values` is empty. * @throws {TypeError|RangeError} If an item cannot be parsed as a decimal. * @private */ static #utmost = ( values, { cmp = (comparison) => comparison > 0 } = {} ) => { if (values == null || typeof values[Symbol.iterator] !== "function") { throw new TypeError("Values must be iterable"); } const items = Array.from(values); if (items.length === 0) { throw new RangeError("At least one value is required"); } let top = new this(items[0]); for (let i = 1; i < items.length; i += 1) { const candidate = new BigDecimal(items[i]); if (cmp(candidate.compareTo(top))) { top = candidate; } } return top; }; /** * Returns the greatest value in the arguments. * * @param {...(BigDecimal|string|number|bigint|null|undefined)} values * One or more values to compare. * @returns {BigDecimal} The greatest value, as a BigDecimal. * @throws {RangeError} If no values are provided. * @throws {TypeError|RangeError} If a value cannot be parsed as a decimal. */ static max(...values) { return BigDecimal.#utmost(values); } /** * Returns the smallest value in the arguments. * * @param {...(BigDecimal|string|number|bigint|null|undefined)} values * One or more values to compare. * @returns {BigDecimal} The smallest value, as a BigDecimal. * @throws {RangeError} If no values are provided. * @throws {TypeError|RangeError} If a value cannot be parsed as a decimal. */ static min(...values) { return BigDecimal.#utmost(values, { cmp: (comparison) => comparison < 0 }); } #register; // a BigInt holding the value multiplied by #scaleFactor #roundingMode; // the rounding mode used by this instance // Aliases defined as getters on the prototype get plus() { return this.add; } get minus() { return this.subtract; } get sub() { return this.subtract; } get mul() { return this.multiply; } get times() { return this.multiply; } get div() { return this.divide; } get eq() { return this.equals; } get gt() { return this.greaterThan; } get gte() { return this.greaterThanOrEquals; } get lt() { return this.lowerThan; } get lte() { return this.lowerThanOrEquals; } get lessThan() { return this.lowerThan; } get lessThanOrEquals() { return this.lowerThanOrEquals; } get numberValue() { return this.valueOf; } get toBigInteger() { return this.toBigInt; } /** * Creates a decimal from a string, number, bigint, or another BigDecimal. * * Nullish and empty-string inputs are treated as zero. String inputs may * use underscores between digits and may use scientific notation, subject * to the configured exponent cap. Values are stored at the configured * scale, with excess fractional digits rounded according to `roundingMode`. * * When `value` is a JavaScript number, its string representation is parsed. * Precision already lost in prior JavaScript numeric calculations cannot * be recovered; use a string for exact decimal input, such as * `new BigDecimal("0.1")`. * * If `value` is an instance of this class in the same realm, that instance * is returned unchanged and any supplied options are ignored. Use * `value.clone({ roundingMode })` to create a copy with a different mode. * * The legacy `rounding: false` option selects `TOWARD_ZERO`. * * @param {string | number | bigint | BigDecimal} [value="0"] The value to * parse. * @param {Object} [flags] Configuration options. * @param {string} [flags.roundingMode] The rounding mode; defaults to * HALF_EVEN when rounding is enabled and TOWARD_ZERO otherwise. * @param {boolean} [flags.rounding=true] Legacy option controlling the * default rounding mode. * @throws {SyntaxError} If the value is not a valid decimal representation. * @throws {RangeError} If the exponent exceeds the configured cap. */ constructor( value, /* flags */ { rounding = true, roundingMode = rounding ? BigDecimal.RoundingMode.HALF_EVEN : BigDecimal.RoundingMode.TOWARD_ZERO, ...flags } = {} ) { /*! * Preserve same-realm BigDecimal instances. Cross-realm instances are * parsed from their string representation below. * * Existing instances are returned unchanged, so constructor options * supplied alongside one are ignored. */ if (value instanceof BigDecimal) { return value; } this.#roundingMode = roundingMode; // Handle internal construction using the secret Symbol key. if (flags[BigDecimal.#semaphore]) { this.#register = value; return; } // Parse scientific notation components. const match = ( null == value ? "0" : String(value) .trim() .replace(/(\d)_(?=\d)/g, "$1") || "0" ).match(parseDecimal); if (!match) { throw new SyntaxError(`Invalid decimal value (${value})`); } const [, sign, wholePart = "0", , fractPart = "", exponent = "0"] = match; if (Math.abs(exponent) > __EXPONENT_CAP__) { throw new RangeError( `Decimal exponent must be between -${__EXPONENT_CAP__} and ${__EXPONENT_CAP__}` ); } let [whole, fract] = normalizeDecimalParts( wholePart, fractPart, exponent ); // Inspect normalized fractional digits before truncating them. This // also accounts for digits shifted by the exponent. const discarded = fract.slice(BigDecimal.#scale); fract = fract .padEnd(BigDecimal.#scale, "0") .slice(0, BigDecimal.#scale); const retainedMagnitude = BigInt(whole + fract); const discardedMagnitude = discarded ? BigInt(discarded) : 0n; const divisor = discarded ? 10n ** BigInt(discarded.length) : 1n; const magnitude = retainedMagnitude * divisor + discardedMagnitude; const dividend = "-" === sign ? -magnitude : magnitude; this.#register = BigDecimal.#divide( dividend, divisor, this.#roundingMode ); } /** * Creates a copy with the same stored value and, optionally, a different * rounding mode. * * @param {Object} [options] Clone options. * @param {string} [options.roundingMode] The rounding mode for the copy; * defaults to this instance's mode. * @returns {BigDecimal} The cloned decimal. */ clone({ roundingMode = this.#roundingMode } = {}) { return BigDecimal.#create(this.#register, roundingMode); } /** * Returns the string tag for this class. * * @returns {string} The class tag. */ get [Symbol.toStringTag]() { return "BigDecimal"; } /** * Restricts the current BigDecimal value to be within the specified range. * If min is greater than max, they are automatically swapped. * * @param {string|number|bigint|BigDecimal} min - The lower bound. * @param {string|number|bigint|BigDecimal} max - The upper bound. * @returns {BigDecimal} The clamped BigDecimal value. */ clamp(min, max) { const { min: _min, max: _max } = BigDecimal; const lower = _min(min, max); const upper = _max(min, max); const result = _max(lower, _min(this, upper)); return result === this ? this : BigDecimal.#create(result, this.#roundingMode); } /** * Returns the absolute value. * * @returns {BigDecimal} The absolute value. */ abs() { const value = this.#register; return BigDecimal.#create( value < 0n ? -value : value, this.#roundingMode ); } ceil() { return this.roundToInteger(BigDecimal.RoundingMode.TOWARD_POSITIVE); } floor() { return this.roundToInteger(BigDecimal.RoundingMode.TOWARD_NEGATIVE); } /** * Returns the negated value. * * @returns {BigDecimal} The negated value. */ neg() { return BigDecimal.#create(-this.#register, this.#roundingMode); } /** * Returns the remainder after dividing this value by `num`. * * The result follows JavaScript BigInt remainder semantics: the quotient is * truncated toward zero, and a nonzero remainder has the sign of the dividend. * `num` is converted to this instance's fixed-point scale and rounding mode. * * @param {BigDecimal | string | number | bigint} num The divisor. * @returns {BigDecimal} The remainder, at the library's fixed scale. * @throws {RangeError} If `num` is zero at the library's fixed scale. */ remainder(num) { const other = new BigDecimal(num, { roundingMode: this.#roundingMode }); return BigDecimal.#create( // In fixed-point arithmetic with the same scale: // (a * scale) % (b * scale) = (a % b) * scale this.#register % other.#register, this.#roundingMode ); } /** * Rounds this value to an integer using the specified rounding mode. * * @param {string} [roundingMode] * The rounding mode. Defaults to this instance's rounding mode. * @returns {BigDecimal} The rounded integer, represented at the configured scale. */ roundToInteger(roundingMode = this.#roundingMode) { const factor = BigDecimal.#scaleFactor; const integer = BigDecimal.#divide( this.#register, factor, roundingMode ); return BigDecimal.#create(integer * factor, this.#roundingMode); } /** * Adds a value, converting the operand with this instance's rounding mode. * * @param {string | number | bigint | BigDecimal} num The value to add. * @returns {BigDecimal} The sum. */ add(num) { const other = new BigDecimal(num, { roundingMode: this.#roundingMode }); return BigDecimal.#create( this.#register + other.#register, this.#roundingMode ); } /** * Subtracts a value, converting the operand with this instance's rounding * mode. * * @param {string | number | bigint | BigDecimal} num The value to subtract. * @returns {BigDecimal} The difference. */ subtract(num) { const other = new BigDecimal(num, { roundingMode: this.#roundingMode }); return BigDecimal.#create( this.#register - other.#register, this.#roundingMode ); } /** * Multiplies by a value and rounds the result using this instance's mode. * * @param {string | number | bigint | BigDecimal} num The multiplier. * @returns {BigDecimal} The product. */ multiply(num) { const other = new BigDecimal(num, { roundingMode: this.#roundingMode }); return BigDecimal.#create( BigDecimal.#divide( this.#register * other.#register, BigDecimal.#scaleFactor, this.#roundingMode ), this.#roundingMode ); } /** * Divides by a value and rounds the result using this instance's mode. * * @param {string | number | bigint | BigDecimal} num The divisor. * @returns {BigDecimal} The quotient. * @throws {RangeError} If the divisor is zero. */ divide(num) { const other = new BigDecimal(num, { roundingMode: this.#roundingMode }); return BigDecimal.#create( BigDecimal.#divide( this.#register * BigDecimal.#scaleFactor, other.#register, this.#roundingMode ), this.#roundingMode ); } /** * Compares this value with another value using their stored fixed-point * registers. * * @param {BigDecimal|string|number|bigint|null|undefined} value * The value to compare with. Non-BigDecimal values are parsed using this * instance's rounding mode and the library's configured scale. * @returns {-1|0|1} `-1` if this value is smaller, `0` if equal, or `1` if larger. * @throws {TypeError|RangeError} If `value` cannot be parsed as a decimal. */ compareTo(value) { const other = new BigDecimal(value, { roundingMode: this.#roundingMode }); if (this.#register < other.#register) return -1; if (this.#register > other.#register) return 1; return 0; } /** * Returns whether this decimal is negative. * @returns {boolean} */ isNegative() { return this.#register < 0n; } /** * Returns whether this decimal is positive. * @returns {boolean} */ isPositive() { return this.#register > 0n; } /** * Returns whether this decimal is zero. * @returns {boolean} */ isZero() { return this.#register === 0n; } /** * Tests whether this value equals another value at the configured scale. * * @param {BigDecimal|string|number|bigint|null|undefined} value * The value to compare with. * @returns {boolean} `true` if the values are equal; otherwise, `false`. * @throws {TypeError|RangeError} If `value` cannot be parsed as a decimal. */ equals(value) { return this.compareTo(value) === 0; } /** * Tests whether this value is larger than another value. * * @param {BigDecimal|string|number|bigint|null|undefined} value * The value to compare with. * @returns {boolean} `true` if this value is larger; otherwise, `false`. * @throws {TypeError|RangeError} If `value` cannot be parsed as a decimal. */ greaterThan(value) { return this.compareTo(value) > 0; } /** * Tests whether this value is larger than or equal to another value. * * @param {BigDecimal|string|number|bigint|null|undefined} value * The value to compare with. * @returns {boolean} `true` if this value is larger than or equal to `value`. * @throws {TypeError|RangeError} If `value` cannot be parsed as a decimal. */ greaterThanOrEquals(value) { return this.compareTo(value) >= 0; } /** * Tests whether this value is smaller than another value. * * @param {BigDecimal|string|number|bigint|null|undefined} value * The value to compare with. * @returns {boolean} `true` if this value is smaller; otherwise, `false`. * @throws {TypeError|RangeError} If `value` cannot be parsed as a decimal. */ lowerThan(value) { return this.compareTo(value) < 0; } /** * Tests whether this value is smaller than or equal to another value. * * @param {BigDecimal|string|number|bigint|null|undefined} value * The value to compare with. * @returns {boolean} `true` if this value is smaller than or equal to `value`. * @throws {TypeError|RangeError} If `value` cannot be parsed as a decimal. */ lowerThanOrEquals(value) { return this.compareTo(value) <= 0; } /** * Alias for {@link equals}, retained for compatibility. * * @param {BigDecimal|string|number|bigint|null|undefined} value * The value to compare with. * @returns {boolean} `true` if the values are equal; otherwise, `false`. * @throws {TypeError|RangeError} If `value` cannot be parsed as a decimal. */ sameValue(value) { return this.equals(value); } /** * Converts this decimal to a Number only if the conversion is exact. * * The method inspects the Float64 bit pattern and compares its exact * binary value with this decimal's scaled integer representation. * * @returns {number} The exactly representable Number value. * @throws {RangeError} If the value is not finite or not exactly * representable as a Number. */ numberValueExact() { const value = Number(String(this)); // `value` is already a number, so global isFinite is safe here. if (isFinite(value)) { const littleEndian = false; const view = new DataView(new ArrayBuffer(8)); view.setFloat64(0, value, littleEndian); // Read the 64-bit pattern as two big-endian 32-bit words. // Combining the words avoids requiring DataView.getBigUint64(). const high = BigInt(view.getUint32(0, littleEndian)); const low = BigInt(view.getUint32(4, littleEndian)); const bits = (high << 32n) | low; const Double = BigDecimal.#Float64; const exponentField = (bits >> Double.fractionBits) & Double.exponentMask; const fraction = bits & Double.fractionMask; const sign = bits >> (Double.totalBits - 1n) === 0n ? 1n : -1n; const significand = sign * (exponentField === 0n ? fraction : (1n << Double.fractionBits) | fraction); const binaryExponent = (exponentField === 0n ? 1 : Number(exponentField)) - Double.exponentBias - Number(Double.fractionBits); const decimalDenominator = 10n ** BigInt(BigDecimal.#scale); const isExact = binaryExponent >= 0 ? this.#register === significand * (1n << BigInt(binaryExponent)) * decimalDenominator : this.#register * (1n << BigInt(-binaryExponent)) === significand * decimalDenominator; if (isExact) { return value; } } throw new RangeError( "Value does not have an exact Number representation" ); } /** * Converts this decimal to a Number if its string form round-trips unchanged. * * This compares `String(Number(String(this)))` with `String(this)`. It checks * string preservation, not whether the decimal and Number have exactly equal * mathematical values. * * @returns {number} The Number value if the string round-trip is unchanged. * @throws {RangeError} If converting to Number changes the string form. */ numberValueIfStringRoundTrips() { const decimalString = String(this); const value = +decimalString; if (String(value) === decimalString) { return value; } throw new RangeError( "Value does not round-trip to the same decimal string" ); } toBigInt() { return ( this.roundToInteger(BigDecimal.RoundingMode.TOWARD_ZERO).#register / BigDecimal.#scaleFactor ); } /** * Returns the decimal's string representation for JSON serialization. * * @returns {string} The decimal representation. */ toJSON() { return String(this); } /** * Returns the decimal representation without trailing fractional zeroes * or exponential notation. * * @returns {string} The decimal representation. */ toString() { const value = this.#register; const isNegative = value < 0n; const scale = BigDecimal.#scale; const digits = (isNegative ? -value : value).toString(); const padded = digits.length <= scale ? digits.padStart(scale + 1, "0") : digits; const point = padded.length - scale; let end = padded.length; while (end > point && padded[end - 1] === "0") { end--; } const sign = isNegative ? "-" : ""; return ( sign + padded.slice(0, point) + (end === point ? "" : "." + padded.slice(point, end)) ); } /** * Returns the approximate native JavaScript number representation. * * Converting to Number can lose precision, particularly for values with * more than 15–17 significant digits. * * @returns {number} The approximate floating-point value. */ valueOf() { return +String(this); } }, { apply(target, _thisArg, argumentsList) { return Reflect.construct(target, argumentsList); } } ); })({ __SCALE__ })3d:[] 38:{"id":"22d16e81e9e301bc","slug":"achieving-fixed-point-decimal-arithmetic-in-javascript","title":"Achieving Fixed-Point Decimal Arithmetic in JavaScript","thumbnail":"f2f83f2d73ec94f742d964413b4edaaa8140fd2907bc3876d160f535db2cd522","access_level":"public","create_time":"$D2026-11-02T21:22:00.036Z","update_time":"$D2026-11-03T23:10:00.717Z","view_time":null,"first_public_time":"$D2026-11-02T21:22:00.036Z","has_unpublished_edits":null,"fork":false,"stars":0,"starred":false,"owner":{"type":"team","id":"4c1622bb5c37477f","login":"galopin","name":"Michaël Guitton","avatar_url":"https://avatars-next.observableusercontent.com/10e2fe999ac95c8686156fd07e96a686520149a4eef18a95f97795b7a7be1e29","tier":"starter_2024","bio":"Over 2 decades of experience on the Web…","followed_by_you":false,"follows_you":false},"version":72,"publish_version":null,"role":null,"authored":false,"authors":[{"type":"individual","id":"950eb34948878085","login":"galopin","name":"Michaël Guitton","avatar_url":"https://avatars-next.observableusercontent.com/b59822ff41962e9448473fadd4a11819ac725b074ad3868aabf532bade0ac00d","tier":null,"bio":"Over three decades of experience on the Web… “Don’t wait for inspiration. It comes while one is working.” ― Henri Matisse","followed_by_you":false,"follows_you":false}],"members":[{"type":"team","id":"4c1622bb5c37477f","login":"galopin","name":"Michaël Guitton","avatar_url":"https://avatars-next.observableusercontent.com/10e2fe999ac95c8686156fd07e96a686520149a4eef18a95f97795b7a7be1e29","tier":"starter_2024","role":"editor"},{"type":"individual","id":"950eb34948878085","login":"galopin","name":"Michaël Guitton","avatar_url":"https://avatars-next.observableusercontent.com/b59822ff41962e9448473fadd4a11819ac725b074ad3868aabf532bade0ac00d","tier":null,"role":"editor"}],"comments":[],"custom_thumbnail":false,"trashed":false,"lapsed":null,"subscribed":null,"forks":1,"collection":null,"type":"notebook","body":{"titling":"auto","title":"Achieving Fixed-Point Decimal Arithmetic in JavaScript","cells":[{"id":0,"value":"$${[\n md`# Achieving Fixed-Point Decimal Arithmetic in JavaScript`,\n md`## Mitigating the Floating-Point Problem via Scaled BigInts`\n].map(($_) =>\n Object.assign($_, {\n style: \"text-wrap: balance;\"\n })\n).concat([html`