iso-price 1.0.3

package/dist/domain.operations/arithmetic/allocatePrice.js

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.priceAllocate = exports.allocatePrice = void 0;
+const helpful_errors_1 = require("helpful-errors");
+const IsoPriceExponent_1 = require("../../domain.objects/IsoPriceExponent");
+const asIsoPriceShape_1 = require("../cast/asIsoPriceShape");
+const asIsoPriceWords_1 = require("../cast/asIsoPriceWords");
+function allocatePrice(input, options) {
+    const shape = (0, asIsoPriceShape_1.asIsoPriceShape)(input.of);
+    const exponent = shape.exponent ?? IsoPriceExponent_1.IsoPriceExponent.CENTI;
+    // handle equal parts allocation
+    if ('parts' in input.into) {
+        const parts = input.into.parts;
+        if (parts < 1) {
+            throw new helpful_errors_1.BadRequestError('cannot allocate into less than 1 part', {
+                input,
+            });
+        }
+        return allocateEqualParts(shape.amount, shape.currency, exponent, parts, input.remainder, options?.format);
+    }
+    // handle ratio allocation
+    const ratios = input.into.ratios;
+    if (ratios.length < 1) {
+        throw new helpful_errors_1.BadRequestError('cannot allocate into less than 1 part', {
+            input,
+        });
+    }
+    return allocateByRatios(shape.amount, shape.currency, exponent, ratios, input.remainder, options?.format);
+}
+exports.allocatePrice = allocatePrice;
+/**
+ * .what = allocates amount into equal parts
+ * .why = splits evenly with remainder distribution
+ */
+const allocateEqualParts = (amount, currency, exponent, parts, remainderMode, format) => {
+    const divisor = BigInt(parts);
+    const baseAmount = amount / divisor;
+    const remainder = amount % divisor;
+    // create base allocations
+    const allocations = Array(parts).fill(baseAmount);
+    // distribute remainder
+    distributeRemainder(allocations, remainder, remainderMode, baseAmount);
+    return formatAllocations(allocations, currency, exponent, format);
+};
+/**
+ * .what = allocates amount by ratios
+ * .why = splits proportionally with remainder distribution
+ */
+const allocateByRatios = (amount, currency, exponent, ratios, remainderMode, format) => {
+    // validate ratios
+    if (ratios.some((r) => r < 0)) {
+        throw new helpful_errors_1.BadRequestError('ratios must be non-negative', { ratios });
+    }
+    const totalRatio = ratios.reduce((sum, r) => sum + r, 0);
+    if (totalRatio === 0) {
+        throw new helpful_errors_1.BadRequestError('total ratio cannot be zero', { ratios });
+    }
+    // calculate base allocations via largest remainder method
+    const totalRatioBigInt = BigInt(totalRatio);
+    const allocations = [];
+    let allocated = 0n;
+    for (let i = 0; i < ratios.length; i++) {
+        const ratio = BigInt(ratios[i]);
+        const allocation = (amount * ratio) / totalRatioBigInt;
+        allocations.push(allocation);
+        allocated += allocation;
+    }
+    // calculate remainder from truncation
+    const remainder = amount - allocated;
+    // distribute remainder
+    distributeRemainder(allocations, remainder, remainderMode, 0n, // for ratio mode, pass 0 as baseAmount (not used for largest)
+    ratios);
+    return formatAllocations(allocations, currency, exponent, format);
+};
+/**
+ * .what = distributes remainder per mode
+ * .why = ensures no cent is lost in allocation
+ */
+const distributeRemainder = (allocations, remainder, mode, baseAmount, ratios) => {
+    // handle negative remainder (can happen with negative amounts)
+    const isNegative = remainder < 0n;
+    const absRemainder = isNegative ? -remainder : remainder;
+    const increment = isNegative ? -1n : 1n;
+    // get indices for distribution
+    const indices = getDistributionIndices(allocations.length, Number(absRemainder), mode, allocations, ratios);
+    // apply remainder distribution
+    for (const idx of indices) {
+        allocations[idx] = allocations[idx] + increment;
+    }
+};
+/**
+ * .what = determines which indices receive remainder cents
+ * .why = implements different distribution strategies
+ */
+const getDistributionIndices = (length, count, mode, allocations, ratios) => {
+    if (count === 0)
+        return [];
+    if (count >= length) {
+        // each gets at least one
+        const indices = Array.from({ length }, (_, i) => i);
+        // distribute extra to first positions
+        const extra = count - length;
+        for (let i = 0; i < extra; i++) {
+            indices.push(i % length);
+        }
+        return indices;
+    }
+    switch (mode) {
+        case 'first':
+            return Array.from({ length: count }, (_, i) => i);
+        case 'last':
+            return Array.from({ length: count }, (_, i) => length - 1 - i);
+        case 'largest': {
+            // hamilton/largest remainder method: give to those with largest fractional parts
+            // for equal parts, all have same fractional part, so fall back to first
+            // for ratios, calculate fractional remainders
+            if (!ratios) {
+                return Array.from({ length: count }, (_, i) => i);
+            }
+            // calculate fractional remainders for each ratio
+            const totalRatio = ratios.reduce((sum, r) => sum + r, 0);
+            const fractions = ratios.map((r, i) => ({
+                index: i,
+                fraction: (r / totalRatio) * Number(allocations.reduce((a, b) => a + b, 0n)) -
+                    Number(allocations[i]),
+            }));
+            // sort by fraction (largest first)
+            fractions.sort((a, b) => b.fraction - a.fraction);
+            return fractions.slice(0, count).map((f) => f.index);
+        }
+        case 'random': {
+            // pseudo-random but deterministic based on allocation values
+            const indices = Array.from({ length }, (_, i) => i);
+            // use a simple deterministic shuffle based on allocation sum
+            const seed = Number(allocations.reduce((a, b) => a + b, 0n) % 1000000n);
+            indices.sort((a, b) => {
+                const hashA = (a * 31 + seed) % 1000;
+                const hashB = (b * 31 + seed) % 1000;
+                return hashA - hashB;
+            });
+            return indices.slice(0, count);
+        }
+        default:
+            return Array.from({ length: count }, (_, i) => i);
+    }
+};
+/**
+ * .what = converts bigint allocations to output format
+ * .why = enables both words and shape output
+ */
+const formatAllocations = (allocations, currency, exponent, format) => {
+    const shapes = allocations.map((amount) => ({
+        amount,
+        currency,
+        exponent: exponent,
+    }));
+    if (format === 'shape') {
+        return shapes;
+    }
+    return shapes.map((s) => (0, asIsoPriceWords_1.asIsoPriceWords)(s));
+};
+/**
+ * .what = alias for allocatePrice
+ * .why = provides price-prefixed variant
+ */
+exports.priceAllocate = allocatePrice;
+//# sourceMappingURL=allocatePrice.js.map

package/dist/domain.operations/arithmetic/allocatePrice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"allocatePrice.js","sourceRoot":"","sources":["../../../src/domain.operations/arithmetic/allocatePrice.ts"],"names":[],"mappings":"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"}

package/dist/domain.operations/arithmetic/dividePrice.d.ts

@@ -0,0 +1,40 @@
+import type { IsoPrice } from '../../domain.objects/IsoPrice';
+import { IsoPriceRoundMode } from '../../domain.objects/IsoPriceRoundMode';
+import type { IsoPriceShape } from '../../domain.objects/IsoPriceShape';
+import type { IsoPriceWords } from '../../domain.objects/IsoPriceWords';
+/**
+ * .what = divides a price by a scalar
+ * .why = enables per-unit calculations and cost breakdowns
+ *
+ * auto-scales precision when divisors are large.
+ * for small divisors, maintains input precision with round.
+ *
+ * @throws BadRequestError if divisor is zero
+ *
+ * @example
+ * dividePrice({ of: 'USD 10.00', by: 4 })
+ * // => 'USD 2.50'
+ *
+ * @example
+ * dividePrice({ of: '$0.25', by: 1_000_000 })
+ * // => 'USD 0.000_000_250' (nano precision)
+ */
+export declare function dividePrice<TCurrency extends string = string>(input: {
+    of: IsoPrice<TCurrency> | string;
+    by: number;
+}, options?: {
+    format?: 'words';
+    round?: IsoPriceRoundMode;
+}): IsoPriceWords<TCurrency>;
+export declare function dividePrice<TCurrency extends string = string>(input: {
+    of: IsoPrice<TCurrency> | string;
+    by: number;
+}, options: {
+    format: 'shape';
+    round?: IsoPriceRoundMode;
+}): IsoPriceShape<TCurrency>;
+/**
+ * .what = alias for dividePrice
+ * .why = provides price-prefixed variant
+ */
+export declare const priceDivide: typeof dividePrice;

package/dist/domain.operations/arithmetic/dividePrice.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.priceDivide = exports.dividePrice = void 0;
+const helpful_errors_1 = require("helpful-errors");
+const IsoPriceExponent_1 = require("../../domain.objects/IsoPriceExponent");
+const IsoPriceRoundMode_1 = require("../../domain.objects/IsoPriceRoundMode");
+const asIsoPriceShape_1 = require("../cast/asIsoPriceShape");
+const asIsoPriceWords_1 = require("../cast/asIsoPriceWords");
+/**
+ * .what = gets the numeric exponent value from exponent string
+ * .why = needed for precision calculation
+ */
+const getExponentValue = (exponent) => {
+    const match = exponent.match(/\^(-?\d+)$/);
+    if (!match)
+        return -2; // default to centi
+    return parseInt(match[1], 10);
+};
+/**
+ * .what = determines required precision based on divisor
+ * .why = ensures result has meaningful precision for large divisors
+ */
+const getRequiredExponent = (inputExponent, divisor) => {
+    const absDivisor = Math.abs(divisor);
+    // for small divisors (< 100), maintain input precision with round
+    if (absDivisor < 100)
+        return inputExponent;
+    // for medium divisors (100 - 999,999), use milli precision
+    if (absDivisor < 1000000)
+        return IsoPriceExponent_1.IsoPriceExponent.MILLI;
+    // for large divisors (1M - 999M), use nano precision
+    if (absDivisor < 1000000000)
+        return IsoPriceExponent_1.IsoPriceExponent.NANO;
+    // for huge divisors, use pico precision
+    return IsoPriceExponent_1.IsoPriceExponent.PICO;
+};
+function dividePrice(input, options) {
+    if (input.by === 0) {
+        throw new helpful_errors_1.BadRequestError('cannot divide by zero', { input });
+    }
+    const shape = (0, asIsoPriceShape_1.asIsoPriceShape)(input.of);
+    const inputExponent = shape.exponent ?? IsoPriceExponent_1.IsoPriceExponent.CENTI;
+    const roundMode = options?.round ?? IsoPriceRoundMode_1.IsoPriceRoundMode.HALF_UP;
+    // determine output precision based on divisor
+    const outputExponent = getRequiredExponent(inputExponent, input.by);
+    const outputExpValue = getExponentValue(outputExponent);
+    const inputExpValue = getExponentValue(inputExponent);
+    // scale amount to output precision
+    const scaleDiff = inputExpValue - outputExpValue;
+    const scaledAmount = shape.amount * 10n ** BigInt(scaleDiff);
+    // perform division with round
+    const divisor = BigInt(Math.round(Math.abs(input.by)));
+    const sign = input.by < 0 ? -1n : 1n;
+    let quotient;
+    const remainder = scaledAmount % divisor;
+    // apply round mode
+    if (remainder === 0n) {
+        quotient = scaledAmount / divisor;
+    }
+    else {
+        const baseQuotient = scaledAmount / divisor;
+        const isNegative = scaledAmount < 0n;
+        const absRemainder = remainder < 0n ? -remainder : remainder;
+        // use doubled remainder for accurate half comparison (avoids truncation from divisor/2)
+        const doubledRemainder = absRemainder * 2n;
+        const isExactlyHalf = doubledRemainder === divisor;
+        const isMoreThanHalf = doubledRemainder > divisor;
+        switch (roundMode) {
+            case IsoPriceRoundMode_1.IsoPriceRoundMode.FLOOR:
+                quotient = isNegative ? baseQuotient - 1n : baseQuotient;
+                break;
+            case IsoPriceRoundMode_1.IsoPriceRoundMode.CEIL:
+                quotient = isNegative ? baseQuotient : baseQuotient + 1n;
+                break;
+            case IsoPriceRoundMode_1.IsoPriceRoundMode.HALF_UP:
+                quotient =
+                    isExactlyHalf || isMoreThanHalf
+                        ? isNegative
+                            ? baseQuotient - 1n
+                            : baseQuotient + 1n
+                        : baseQuotient;
+                break;
+            case IsoPriceRoundMode_1.IsoPriceRoundMode.HALF_DOWN:
+                quotient = isMoreThanHalf
+                    ? isNegative
+                        ? baseQuotient - 1n
+                        : baseQuotient + 1n
+                    : baseQuotient;
+                break;
+            case IsoPriceRoundMode_1.IsoPriceRoundMode.HALF_EVEN: {
+                const isEven = baseQuotient % 2n === 0n;
+                if (isExactlyHalf) {
+                    quotient = isEven ? baseQuotient : baseQuotient + 1n;
+                }
+                else if (isMoreThanHalf) {
+                    quotient = isNegative ? baseQuotient - 1n : baseQuotient + 1n;
+                }
+                else {
+                    quotient = baseQuotient;
+                }
+                break;
+            }
+            default:
+                quotient = baseQuotient;
+        }
+    }
+    // apply divisor sign
+    quotient = quotient * sign;
+    // build result shape
+    const resultShape = {
+        amount: quotient,
+        currency: shape.currency,
+        exponent: outputExponent,
+    };
+    // return in requested format
+    if (options?.format === 'shape') {
+        return resultShape;
+    }
+    return (0, asIsoPriceWords_1.asIsoPriceWords)(resultShape);
+}
+exports.dividePrice = dividePrice;
+/**
+ * .what = alias for dividePrice
+ * .why = provides price-prefixed variant
+ */
+exports.priceDivide = dividePrice;
+//# sourceMappingURL=dividePrice.js.map

package/dist/domain.operations/arithmetic/dividePrice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dividePrice.js","sourceRoot":"","sources":["../../../src/domain.operations/arithmetic/dividePrice.ts"],"names":[],"mappings":"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"}

package/dist/domain.operations/arithmetic/multiplyPrice.d.ts

@@ -0,0 +1,38 @@
+import type { IsoPrice } from '../../domain.objects/IsoPrice';
+import { IsoPriceRoundMode } from '../../domain.objects/IsoPriceRoundMode';
+import type { IsoPriceShape } from '../../domain.objects/IsoPriceShape';
+import type { IsoPriceWords } from '../../domain.objects/IsoPriceWords';
+/**
+ * .what = multiplies a price by a scalar
+ * .why = enables quantity calculations and percentage markups
+ *
+ * maintains input precision by default. uses higher internal precision
+ * to avoid intermediate loss, then rounds back to input precision.
+ *
+ * @example
+ * multiplyPrice({ of: 'USD 10.00', by: 3 })
+ * // => 'USD 30.00'
+ *
+ * @example
+ * multiplyPrice({ of: 'USD 100.00', by: 1.08 })
+ * // => 'USD 108.00' (tax markup)
+ */
+export declare function multiplyPrice<TCurrency extends string = string>(input: {
+    of: IsoPrice<TCurrency> | string;
+    by: number;
+}, options?: {
+    format?: 'words';
+    round?: IsoPriceRoundMode;
+}): IsoPriceWords<TCurrency>;
+export declare function multiplyPrice<TCurrency extends string = string>(input: {
+    of: IsoPrice<TCurrency> | string;
+    by: number;
+}, options: {
+    format: 'shape';
+    round?: IsoPriceRoundMode;
+}): IsoPriceShape<TCurrency>;
+/**
+ * .what = alias for multiplyPrice
+ * .why = provides price-prefixed variant
+ */
+export declare const priceMultiply: typeof multiplyPrice;

package/dist/domain.operations/arithmetic/multiplyPrice.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.priceMultiply = exports.multiplyPrice = void 0;
+const IsoPriceExponent_1 = require("../../domain.objects/IsoPriceExponent");
+const IsoPriceRoundMode_1 = require("../../domain.objects/IsoPriceRoundMode");
+const asIsoPriceShape_1 = require("../cast/asIsoPriceShape");
+const asIsoPriceWords_1 = require("../cast/asIsoPriceWords");
+/**
+ * .what = gets the numeric exponent value from exponent string
+ * .why = needed for precision scale
+ */
+const getExponentValue = (exponent) => {
+    const match = exponent.match(/\^(-?\d+)$/);
+    if (!match)
+        return -2; // default to centi
+    return parseInt(match[1], 10);
+};
+/**
+ * .what = applies round mode to a bigint
+ * .why = needed to round back to input precision
+ */
+const applyRound = (amount, divisor, mode) => {
+    const quotient = amount / divisor;
+    const remainder = amount % divisor;
+    if (remainder === 0n)
+        return quotient;
+    const isNegative = amount < 0n;
+    const absRemainder = remainder < 0n ? -remainder : remainder;
+    const halfDivisor = divisor / 2n;
+    switch (mode) {
+        case IsoPriceRoundMode_1.IsoPriceRoundMode.FLOOR:
+            return isNegative ? quotient - 1n : quotient;
+        case IsoPriceRoundMode_1.IsoPriceRoundMode.CEIL:
+            return isNegative ? quotient : quotient + 1n;
+        case IsoPriceRoundMode_1.IsoPriceRoundMode.HALF_UP:
+            return absRemainder >= halfDivisor
+                ? isNegative
+                    ? quotient - 1n
+                    : quotient + 1n
+                : quotient;
+        case IsoPriceRoundMode_1.IsoPriceRoundMode.HALF_DOWN:
+            return absRemainder > halfDivisor
+                ? isNegative
+                    ? quotient - 1n
+                    : quotient + 1n
+                : quotient;
+        case IsoPriceRoundMode_1.IsoPriceRoundMode.HALF_EVEN: {
+            const isEven = quotient % 2n === 0n;
+            if (absRemainder === halfDivisor) {
+                return isEven ? quotient : quotient + 1n;
+            }
+            return absRemainder > halfDivisor
+                ? isNegative
+                    ? quotient - 1n
+                    : quotient + 1n
+                : quotient;
+        }
+        default:
+            return quotient;
+    }
+};
+function multiplyPrice(input, options) {
+    const shape = (0, asIsoPriceShape_1.asIsoPriceShape)(input.of);
+    const inputExponent = shape.exponent ?? IsoPriceExponent_1.IsoPriceExponent.CENTI;
+    const roundMode = options?.round ?? IsoPriceRoundMode_1.IsoPriceRoundMode.HALF_UP;
+    // scale multiplier to avoid float precision issues (use 12 decimal places)
+    const scaleFactor = BigInt(Math.round(input.by * 1e12));
+    const multiplied = shape.amount * scaleFactor;
+    // round back to original precision
+    const rounded = applyRound(multiplied, BigInt(1e12), roundMode);
+    // build result shape
+    const resultShape = {
+        amount: rounded,
+        currency: shape.currency,
+        exponent: inputExponent,
+    };
+    // return in requested format
+    if (options?.format === 'shape') {
+        return resultShape;
+    }
+    return (0, asIsoPriceWords_1.asIsoPriceWords)(resultShape);
+}
+exports.multiplyPrice = multiplyPrice;
+/**
+ * .what = alias for multiplyPrice
+ * .why = provides price-prefixed variant
+ */
+exports.priceMultiply = multiplyPrice;
+//# sourceMappingURL=multiplyPrice.js.map

package/dist/domain.operations/arithmetic/multiplyPrice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"multiplyPrice.js","sourceRoot":"","sources":["../../../src/domain.operations/arithmetic/multiplyPrice.ts"],"names":[],"mappings":"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"}

package/dist/domain.operations/arithmetic/subPrices.d.ts

@@ -0,0 +1,28 @@
+import type { IsoPrice } from '../../domain.objects/IsoPrice';
+import type { IsoPriceShape } from '../../domain.objects/IsoPriceShape';
+import type { IsoPriceWords } from '../../domain.objects/IsoPriceWords';
+/**
+ * .what = subtracts second price from first
+ * .why = enables price difference computation
+ *
+ * @throws BadRequestError if currencies do not match
+ *
+ * @example
+ * subPrices('USD 50.00', 'USD 20.00')
+ * // => 'USD 30.00'
+ *
+ * @example
+ * subPrices('USD 10.00', 'USD 50.00')
+ * // => 'USD -40.00' (negative allowed)
+ */
+export declare function subPrices<TCurrency extends string = string>(minuend: IsoPrice<TCurrency> | string, subtrahend: IsoPrice<TCurrency> | string, options?: {
+    format?: 'words';
+}): IsoPriceWords<TCurrency>;
+export declare function subPrices<TCurrency extends string = string>(minuend: IsoPrice<TCurrency> | string, subtrahend: IsoPrice<TCurrency> | string, options: {
+    format: 'shape';
+}): IsoPriceShape<TCurrency>;
+/**
+ * .what = alias for subPrices
+ * .why = provides price-prefixed variant
+ */
+export declare const priceSub: typeof subPrices;

package/dist/domain.operations/arithmetic/subPrices.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.priceSub = exports.subPrices = void 0;
+const helpful_errors_1 = require("helpful-errors");
+const IsoPriceExponent_1 = require("../../domain.objects/IsoPriceExponent");
+const asIsoPriceShape_1 = require("../cast/asIsoPriceShape");
+const asIsoPriceWords_1 = require("../cast/asIsoPriceWords");
+/**
+ * .what = gets the numeric exponent value from exponent string
+ * .why = needed for precision comparison and normalization
+ */
+const getExponentValue = (exponent) => {
+    const match = exponent.match(/\^(-?\d+)$/);
+    if (!match)
+        return -2; // default to centi
+    return parseInt(match[1], 10);
+};
+function subPrices(minuend, subtrahend, options) {
+    // convert to shapes
+    const minuendShape = (0, asIsoPriceShape_1.asIsoPriceShape)(minuend);
+    const subtrahendShape = (0, asIsoPriceShape_1.asIsoPriceShape)(subtrahend);
+    // verify currencies match
+    if (minuendShape.currency !== subtrahendShape.currency) {
+        throw new helpful_errors_1.BadRequestError('currency mismatch in price subtraction', {
+            minuend: minuendShape.currency,
+            subtrahend: subtrahendShape.currency,
+        });
+    }
+    const currency = minuendShape.currency;
+    // find the highest precision (lowest exponent value)
+    const minuendExp = getExponentValue(minuendShape.exponent ?? IsoPriceExponent_1.IsoPriceExponent.CENTI);
+    const subtrahendExp = getExponentValue(subtrahendShape.exponent ?? IsoPriceExponent_1.IsoPriceExponent.CENTI);
+    const targetExponentValue = Math.min(minuendExp, subtrahendExp);
+    const targetExponent = minuendExp <= subtrahendExp
+        ? (minuendShape.exponent ?? IsoPriceExponent_1.IsoPriceExponent.CENTI)
+        : (subtrahendShape.exponent ?? IsoPriceExponent_1.IsoPriceExponent.CENTI);
+    // normalize amounts to target precision
+    const minuendShift = minuendExp - targetExponentValue;
+    const subtrahendShift = subtrahendExp - targetExponentValue;
+    const normalizedMinuend = minuendShape.amount * 10n ** BigInt(minuendShift);
+    const normalizedSubtrahend = subtrahendShape.amount * 10n ** BigInt(subtrahendShift);
+    // compute difference
+    const difference = normalizedMinuend - normalizedSubtrahend;
+    // build result shape
+    const resultShape = {
+        amount: difference,
+        currency,
+        exponent: targetExponent,
+    };
+    // return in requested format
+    if (options?.format === 'shape') {
+        return resultShape;
+    }
+    return (0, asIsoPriceWords_1.asIsoPriceWords)(resultShape);
+}
+exports.subPrices = subPrices;
+/**
+ * .what = alias for subPrices
+ * .why = provides price-prefixed variant
+ */
+exports.priceSub = subPrices;
+//# sourceMappingURL=subPrices.js.map

package/dist/domain.operations/arithmetic/subPrices.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subPrices.js","sourceRoot":"","sources":["../../../src/domain.operations/arithmetic/subPrices.ts"],"names":[],"mappings":";;;AAAA,mDAAiD;AAGjD,4EAAyE;AAGzE,6DAA0D;AAC1D,6DAA0D;AAE1D;;;GAGG;AACH,MAAM,gBAAgB,GAAG,CAAC,QAAmC,EAAU,EAAE;IACvE,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IAC3C,IAAI,CAAC,KAAK;QAAE,OAAO,CAAC,CAAC,CAAC,CAAC,mBAAmB;IAC1C,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAE,EAAE,EAAE,CAAC,CAAC;AACjC,CAAC,CAAC;AA0BF,SAAgB,SAAS,CACvB,OAAqC,EACrC,UAAwC,EACxC,OAAwC;IAExC,oBAAoB;IACpB,MAAM,YAAY,GAAG,IAAA,iCAAe,EAAC,OAAO,CAAC,CAAC;IAC9C,MAAM,eAAe,GAAG,IAAA,iCAAe,EAAC,UAAU,CAAC,CAAC;IAEpD,0BAA0B;IAC1B,IAAI,YAAY,CAAC,QAAQ,KAAK,eAAe,CAAC,QAAQ,EAAE,CAAC;QACvD,MAAM,IAAI,gCAAe,CAAC,wCAAwC,EAAE;YAClE,OAAO,EAAE,YAAY,CAAC,QAAQ;YAC9B,UAAU,EAAE,eAAe,CAAC,QAAQ;SACrC,CAAC,CAAC;IACL,CAAC;IAED,MAAM,QAAQ,GAAG,YAAY,CAAC,QAAqB,CAAC;IAEpD,qDAAqD;IACrD,MAAM,UAAU,GAAG,gBAAgB,CACjC,YAAY,CAAC,QAAQ,IAAI,mCAAgB,CAAC,KAAK,CAChD,CAAC;IACF,MAAM,aAAa,GAAG,gBAAgB,CACpC,eAAe,CAAC,QAAQ,IAAI,mCAAgB,CAAC,KAAK,CACnD,CAAC;IACF,MAAM,mBAAmB,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;IAChE,MAAM,cAAc,GAClB,UAAU,IAAI,aAAa;QACzB,CAAC,CAAC,CAAC,YAAY,CAAC,QAAQ,IAAI,mCAAgB,CAAC,KAAK,CAAC;QACnD,CAAC,CAAC,CAAC,eAAe,CAAC,QAAQ,IAAI,mCAAgB,CAAC,KAAK,CAAC,CAAC;IAE3D,wCAAwC;IACxC,MAAM,YAAY,GAAG,UAAU,GAAG,mBAAmB,CAAC;IACtD,MAAM,eAAe,GAAG,aAAa,GAAG,mBAAmB,CAAC;IAC5D,MAAM,iBAAiB,GAAG,YAAY,CAAC,MAAM,GAAG,GAAG,IAAI,MAAM,CAAC,YAAY,CAAC,CAAC;IAC5E,MAAM,oBAAoB,GACxB,eAAe,CAAC,MAAM,GAAG,GAAG,IAAI,MAAM,CAAC,eAAe,CAAC,CAAC;IAE1D,qBAAqB;IACrB,MAAM,UAAU,GAAG,iBAAiB,GAAG,oBAAoB,CAAC;IAE5D,qBAAqB;IACrB,MAAM,WAAW,GAA6B;QAC5C,MAAM,EAAE,UAAU;QAClB,QAAQ;QACR,QAAQ,EAAE,cAAkC;KAC7C,CAAC;IAEF,6BAA6B;IAC7B,IAAI,OAAO,EAAE,MAAM,KAAK,OAAO,EAAE,CAAC;QAChC,OAAO,WAAW,CAAC;IACrB,CAAC;IACD,OAAO,IAAA,iCAAe,EAAC,WAAW,CAAC,CAAC;AACtC,CAAC;AAtDD,8BAsDC;AAED;;;GAGG;AACU,QAAA,QAAQ,GAAG,SAAS,CAAC"}

package/dist/domain.operations/arithmetic/sumPrices.d.ts

@@ -0,0 +1,44 @@
+import type { IsoPrice } from '../../domain.objects/IsoPrice';
+import type { IsoPriceShape } from '../../domain.objects/IsoPriceShape';
+import type { IsoPriceWords } from '../../domain.objects/IsoPriceWords';
+/**
+ * .what = sums multiple prices
+ * .why = enables price aggregation with mixed precision support
+ *
+ * supports two call signatures:
+ * - spread: `sumPrices('USD 10.00', 'USD 20.00')`
+ * - array: `sumPrices(['USD 10.00', 'USD 20.00'])`
+ * - with options: `sumPrices(['USD 10.00'], { format: 'shape' })`
+ *
+ * @throws BadRequestError if currencies do not match
+ *
+ * @example
+ * sumPrices('USD 10.00', 'USD 20.00')
+ * // => 'USD 30.00'
+ *
+ * @example
+ * sumPrices(['USD 10.00', 'USD 20.00'], { format: 'shape' })
+ * // => { amount: 3000n, currency: 'USD' }
+ */
+export declare function sumPrices<TCurrency extends string = string>(...args: (IsoPrice<TCurrency> | string)[]): IsoPriceWords<TCurrency>;
+export declare function sumPrices<TCurrency extends string = string>(prices: (IsoPrice<TCurrency> | string)[], options?: {
+    format?: 'words';
+}): IsoPriceWords<TCurrency>;
+export declare function sumPrices<TCurrency extends string = string>(prices: (IsoPrice<TCurrency> | string)[], options: {
+    format: 'shape';
+}): IsoPriceShape<TCurrency>;
+/**
+ * .what = alias for sumPrices
+ * .why = provides semantic name for binary addition
+ */
+export declare const addPrices: typeof sumPrices;
+/**
+ * .what = alias for sumPrices
+ * .why = provides price-prefixed variant
+ */
+export declare const priceSum: typeof sumPrices;
+/**
+ * .what = alias for sumPrices
+ * .why = provides price-prefixed variant
+ */
+export declare const priceAdd: typeof sumPrices;