jg-bignumber 0.0.0-stage → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## 1.0.1
+
+### Changed
+
+- Published by CI from `jesusgraterol/jg-packages`, with npm provenance. The code is the same as 1.0.0.
+
+## 1.0.0
+
+The first release of `jg-bignumber`, which replaces `bignumber-utils` 1.1.0.
+
+### Added
+
+- `BigNumber`, the package's own bignumber.js constructor.
+- `ERRORS`, the codes of every error the package throws.
+
+### Changed
+
+- `decimalPlaces` applies to every rounding mode, including `*_CEIL` and `*_FLOOR`.
+- `NaN` and `±Infinity` are rejected as `INVALID_VALUE`.
+- `calculateWeightedEntry` returns 0 when the amounts add up to 0.
+- The package no longer changes the global bignumber.js configuration, and it uses bignumber.js 11.
+- Errors are `Exception`s from `jg-exception`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jesus Graterol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,68 @@
-# Temporary Holding Version
+# jg-bignumber
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Exact decimal math with bignumber.js: rounding, formatting, and sum, mean, percentage, and exchange calculations.
+
+## Install
+
+```bash
+npm install jg-bignumber
+```
+
+## Usage
+
+Every calculation is exact, then rounded to 2 decimal places with `ROUND_HALF_UP` and returned as a number, unless the configuration asks otherwise:
+
+```ts
+import { calculateSum, processValue, prettifyValue } from 'jg-bignumber';
+
+calculateSum([0.1, '0.2', 0.3]); // 0.6, not 0.6000000000000001
+processValue(512.155); // 512.16
+processValue(19.991, { roundingMode: 'ROUND_CEIL' }); // 20
+processValue('0.000001', { decimalPlaces: 6, type: 'string' }); // '0.000001'
+prettifyValue(1234.5, { format: { prefix: '$' } }); // '$1,234.5'
+```
+
+Percentages and money:
+
+```ts
+import {
+  adjustByPercentage,
+  calculateExchange,
+  calculatePercentageChange,
+  calculateWeightedEntry,
+} from 'jg-bignumber';
+
+calculatePercentageChange(100, 125); // 25
+adjustByPercentage(100, -10); // 90
+calculateExchange(100, 65000, { decimalPlaces: 8 }); // 0.00153846
+calculateWeightedEntry([
+  [100, 2],
+  [130, 1],
+]); // 110, the average price weighted by amount
+```
+
+`BigNumber` is the package's own bignumber.js constructor, so creating values with it never changes the global bignumber.js configuration.
+
+## Coming from `bignumber-utils`
+
+| `bignumber-utils`                                                         | `jg-bignumber`                             |
+| ------------------------------------------------------------------------- | ------------------------------------------ |
+| `import … from 'bignumber-utils'`                                         | `import … from 'jg-bignumber'`             |
+| `import { BigNumber } from 'bignumber.js'` for values the package accepts | `import { BigNumber } from 'jg-bignumber'` |
+
+Changed behavior:
+
+- `decimalPlaces` applies to every rounding mode. The `*_CEIL` and `*_FLOOR` modes used to force 0 decimal places; pass `decimalPlaces: 0` for that.
+- `NaN` and `±Infinity` are rejected: `getBigNumber`, `processValue`, and the calculations throw `INVALID_VALUE`, and `isNumber` returns `false`.
+- Importing the package no longer changes the global bignumber.js configuration.
+- `calculateWeightedEntry` returns 0 when the amounts add up to 0, instead of failing.
+- Errors are `Exception`s from `jg-exception`, with the same codes, exported as `ERRORS`.
+- The package uses bignumber.js 11, whose `IBigNumberFormat` adds `negativeSign` and `positiveSign`.
+
+## Documentation
+
+The full API reference is at https://jg-packages.jesusgraterol.dev/packages/jg-bignumber/.
+
+## License
+
+[MIT](https://github.com/jesusgraterol/jg-packages/blob/main/packages/jg-bignumber/LICENSE)

package/dist/calculations/calculations.d.ts

@@ -0,0 +1,183 @@
+import type { IBigNumberValue, IConfig, IOutput } from '../shared/types.js';
+/**
+ * Adds up a list of values. An empty list sums to 0.
+ * @param values The values.
+ * @param config How the result is processed.
+ * @returns The sum.
+ * @example
+ * calculateSum([0.1, '0.2', 0.3]); // 0.6
+ * calculateSum([0.1, 0.2], { type: 'string' }); // '0.3'
+ * @throws
+ * - INVALID_VALUE: if any of the given values isn't a finite number or BigNumber throws an error
+ * - INVALID_DECIMAL_PLACES: if the number of decimal places is invalid for any reason
+ * - INVALID_ROUNDING_MODE: if the rounding mode name is not supported
+ * - INVALID_TYPE: if the processing type is not supported
+ * - INVALID_VALUES_ARRAY: if the provided values arg is not a valid array
+ */
+export declare const calculateSum: <T extends Partial<IConfig>>(values: IBigNumberValue[], config?: T) => IOutput<T>;
+/**
+ * Finds the smallest value in a list. An empty list returns 0.
+ * @param values The values.
+ * @param config How the result is processed.
+ * @returns The smallest value.
+ * @example
+ * calculateMin([3, '1.5', 2]); // 1.5
+ * @throws
+ * - INVALID_VALUE: if any of the given values isn't a finite number or BigNumber throws an error
+ * - INVALID_DECIMAL_PLACES: if the number of decimal places is invalid for any reason
+ * - INVALID_ROUNDING_MODE: if the rounding mode name is not supported
+ * - INVALID_TYPE: if the processing type is not supported
+ * - INVALID_VALUES_ARRAY: if the provided values arg is not a valid array
+ */
+export declare const calculateMin: <T extends Partial<IConfig>>(values: IBigNumberValue[], config?: T) => IOutput<T>;
+/**
+ * Finds the largest value in a list. An empty list returns 0.
+ * @param values The values.
+ * @param config How the result is processed.
+ * @returns The largest value.
+ * @example
+ * calculateMax([3, '1.5', 2]); // 3
+ * @throws
+ * - INVALID_VALUE: if any of the given values isn't a finite number or BigNumber throws an error
+ * - INVALID_DECIMAL_PLACES: if the number of decimal places is invalid for any reason
+ * - INVALID_ROUNDING_MODE: if the rounding mode name is not supported
+ * - INVALID_TYPE: if the processing type is not supported
+ * - INVALID_VALUES_ARRAY: if the provided values arg is not a valid array
+ */
+export declare const calculateMax: <T extends Partial<IConfig>>(values: IBigNumberValue[], config?: T) => IOutput<T>;
+/**
+ * Calculates the mean of a list of values. An empty list returns 0.
+ * @param values The values.
+ * @param config How the result is processed.
+ * @returns The mean.
+ * @example
+ * calculateMean([1, 2, 4]); // 2.33
+ * @throws
+ * - INVALID_VALUE: if any of the given values isn't a finite number or BigNumber throws an error
+ * - INVALID_DECIMAL_PLACES: if the number of decimal places is invalid for any reason
+ * - INVALID_ROUNDING_MODE: if the rounding mode name is not supported
+ * - INVALID_TYPE: if the processing type is not supported
+ * - INVALID_VALUES_ARRAY: if the provided values arg is not a valid array
+ */
+export declare const calculateMean: <T extends Partial<IConfig>>(values: IBigNumberValue[], config?: T) => IOutput<T>;
+/**
+ * Calculates the median of a list of values: the middle value, or the mean of the two middle
+ * values when the list has an even length. An empty list returns 0.
+ * @param values The values.
+ * @param config How the result is processed.
+ * @returns The median.
+ * @example
+ * calculateMedian([5, 1, 3]); // 3
+ * calculateMedian([4, 1, 3, 2]); // 2.5
+ * @throws
+ * - INVALID_VALUE: if any of the given values isn't a finite number or BigNumber throws an error
+ * - INVALID_DECIMAL_PLACES: if the number of decimal places is invalid for any reason
+ * - INVALID_ROUNDING_MODE: if the rounding mode name is not supported
+ * - INVALID_TYPE: if the processing type is not supported
+ * - INVALID_VALUES_ARRAY: if the provided values arg is not a valid array
+ */
+export declare const calculateMedian: <T extends Partial<IConfig>>(values: IBigNumberValue[], config?: T) => IOutput<T>;
+/**
+ * Calculates the percentage a value changed by: positive when it increased, negative when it
+ * decreased, and 0 when it didn't change. The largest decrease is -100%, returned whenever the new
+ * value is 0 or less.
+ * @param oldValue The value before the change.
+ * @param newValue The value after the change.
+ * @param config How the result is processed.
+ * @returns The percentage change.
+ * @example
+ * calculatePercentageChange(100, 125); // 25
+ * calculatePercentageChange(100, 80); // -20
+ * calculatePercentageChange(100, 0); // -100
+ * @throws
+ * - INVALID_VALUE: if any of the given values isn't a finite number or BigNumber throws an error
+ * - INVALID_DECIMAL_PLACES: if the number of decimal places is invalid for any reason
+ * - INVALID_ROUNDING_MODE: if the rounding mode name is not supported
+ * - INVALID_TYPE: if the processing type is not supported
+ * - NEGATIVE_VALUE_NOT_ALLOWED: if the oldValue is not positive
+ */
+export declare const calculatePercentageChange: <T extends Partial<IConfig>>(oldValue: IBigNumberValue, newValue: IBigNumberValue, config?: T) => IOutput<T>;
+/**
+ * Changes a value by a percentage: a positive percentage increases it, and a negative one
+ * decreases it, to 0 at most.
+ * @param value The value to change.
+ * @param percentage The percentage to change it by.
+ * @param config How the result is processed.
+ * @returns The changed value.
+ * @example
+ * adjustByPercentage(100, 25); // 125
+ * adjustByPercentage(100, -10); // 90
+ * @throws
+ * - INVALID_VALUE: if any of the given values isn't a finite number or BigNumber throws an error
+ * - INVALID_DECIMAL_PLACES: if the number of decimal places is invalid for any reason
+ * - INVALID_ROUNDING_MODE: if the rounding mode name is not supported
+ * - INVALID_TYPE: if the processing type is not supported
+ * - NEGATIVE_VALUE_NOT_ALLOWED: if the value is not positive
+ */
+export declare const adjustByPercentage: <T extends Partial<IConfig>>(value: IBigNumberValue, percentage: IBigNumberValue, config?: T) => IOutput<T>;
+/**
+ * Calculates what percentage of a total a value represents.
+ * @param value The part.
+ * @param total The total.
+ * @param config How the result is processed.
+ * @returns The percentage.
+ * @example
+ * calculatePercentageRepresentation(25, 200); // 12.5
+ * @throws
+ * - INVALID_VALUE: if any of the given values isn't a finite number or BigNumber throws an error
+ * - INVALID_DECIMAL_PLACES: if the number of decimal places is invalid for any reason
+ * - INVALID_ROUNDING_MODE: if the rounding mode name is not supported
+ * - INVALID_TYPE: if the processing type is not supported
+ * - NEGATIVE_VALUE_NOT_ALLOWED: if the value or total are not positive
+ */
+export declare const calculatePercentageRepresentation: <T extends Partial<IConfig>>(value: IBigNumberValue, total: IBigNumberValue, config?: T) => IOutput<T>;
+/**
+ * Calculates the amount of an asset an exchange gives for a value at a rate, such as how much
+ * BTC 100 USDT buys at 65,000 USDT per BTC.
+ * @param value The amount being exchanged.
+ * @param rate The price of one unit of the asset received.
+ * @param config How the result is processed.
+ * @returns The amount received.
+ * @example
+ * calculateExchange(100, 65000, { decimalPlaces: 8 }); // 0.00153846
+ * @throws
+ * - INVALID_VALUE: if any of the given values isn't a finite number or BigNumber throws an error
+ * - INVALID_DECIMAL_PLACES: if the number of decimal places is invalid for any reason
+ * - INVALID_ROUNDING_MODE: if the rounding mode name is not supported
+ * - INVALID_TYPE: if the processing type is not supported
+ * - NEGATIVE_VALUE_NOT_ALLOWED: if the value or rate are not positive
+ */
+export declare const calculateExchange: <T extends Partial<IConfig>>(value: IBigNumberValue, rate: IBigNumberValue, config?: T) => IOutput<T>;
+/**
+ * Calculates the fee charged for an exchange, as a percentage of the value exchanged.
+ * @param value The amount being exchanged.
+ * @param feePercentage The fee, as a percentage.
+ * @param config How the result is processed.
+ * @returns The fee.
+ * @example
+ * calculateExchangeFee(1000, 0.1); // 1
+ * @throws
+ * - INVALID_VALUE: if any of the given values isn't a finite number or BigNumber throws an error
+ * - INVALID_DECIMAL_PLACES: if the number of decimal places is invalid for any reason
+ * - INVALID_ROUNDING_MODE: if the rounding mode name is not supported
+ * - INVALID_TYPE: if the processing type is not supported
+ * - NEGATIVE_VALUE_NOT_ALLOWED: if the value or feePercentage are not positive
+ */
+export declare const calculateExchangeFee: <T extends Partial<IConfig>>(value: IBigNumberValue, feePercentage: IBigNumberValue, config?: T) => IOutput<T>;
+/**
+ * Calculates the average entry price of a position bought in several trades, weighting each price
+ * by the amount bought. An empty list, or one whose amounts add up to 0, returns 0.
+ * @param trades The trades, each as a `[price, amount]` tuple.
+ * @param config How the result is processed.
+ * @returns The weighted average price.
+ * @example
+ * calculateWeightedEntry([[100, 2], [130, 1]]); // 110
+ * calculateWeightedEntry([]); // 0
+ * @throws
+ * - INVALID_VALUE: if any of the given values isn't a finite number or BigNumber throws an error
+ * - INVALID_DECIMAL_PLACES: if the number of decimal places is invalid for any reason
+ * - INVALID_ROUNDING_MODE: if the rounding mode name is not supported
+ * - INVALID_TYPE: if the processing type is not supported
+ * - INVALID_VALUES_ARRAY: if the provided values arg is not a valid array
+ */
+export declare const calculateWeightedEntry: <T extends Partial<IConfig>>(trades: [IBigNumberValue, IBigNumberValue][], config?: T) => IOutput<T>;

package/dist/calculations/calculations.js

@@ -0,0 +1,289 @@
+import { BigNumber } from '../shared/constants.js';
+import { getBigNumber, processValue } from '../processing/processing.js';
+import { sortBigNumbers } from '../utils/utils.js';
+import { validatePositiveValue, validateValuesArray } from '../validations/validations.js';
+/*
+ * Essential calculations
+ */
+/**
+ * Adds up a list of values. An empty list sums to 0.
+ * @param values The values.
+ * @param config How the result is processed.
+ * @returns The sum.
+ * @example
+ * calculateSum([0.1, '0.2', 0.3]); // 0.6
+ * calculateSum([0.1, 0.2], { type: 'string' }); // '0.3'
+ * @throws
+ * - INVALID_VALUE: if any of the given values isn't a finite number or BigNumber throws an error
+ * - INVALID_DECIMAL_PLACES: if the number of decimal places is invalid for any reason
+ * - INVALID_ROUNDING_MODE: if the rounding mode name is not supported
+ * - INVALID_TYPE: if the processing type is not supported
+ * - INVALID_VALUES_ARRAY: if the provided values arg is not a valid array
+ */
+export const calculateSum = (values, config) => {
+    validateValuesArray(values, 'calculateSum');
+    return processValue(values.length > 0 ? BigNumber.sum(...values) : 0, config);
+};
+/**
+ * Finds the smallest value in a list. An empty list returns 0.
+ * @param values The values.
+ * @param config How the result is processed.
+ * @returns The smallest value.
+ * @example
+ * calculateMin([3, '1.5', 2]); // 1.5
+ * @throws
+ * - INVALID_VALUE: if any of the given values isn't a finite number or BigNumber throws an error
+ * - INVALID_DECIMAL_PLACES: if the number of decimal places is invalid for any reason
+ * - INVALID_ROUNDING_MODE: if the rounding mode name is not supported
+ * - INVALID_TYPE: if the processing type is not supported
+ * - INVALID_VALUES_ARRAY: if the provided values arg is not a valid array
+ */
+export const calculateMin = (values, config) => {
+    validateValuesArray(values, 'calculateMin');
+    return processValue(values.length > 0 ? BigNumber.min(...values) : 0, config);
+};
+/**
+ * Finds the largest value in a list. An empty list returns 0.
+ * @param values The values.
+ * @param config How the result is processed.
+ * @returns The largest value.
+ * @example
+ * calculateMax([3, '1.5', 2]); // 3
+ * @throws
+ * - INVALID_VALUE: if any of the given values isn't a finite number or BigNumber throws an error
+ * - INVALID_DECIMAL_PLACES: if the number of decimal places is invalid for any reason
+ * - INVALID_ROUNDING_MODE: if the rounding mode name is not supported
+ * - INVALID_TYPE: if the processing type is not supported
+ * - INVALID_VALUES_ARRAY: if the provided values arg is not a valid array
+ */
+export const calculateMax = (values, config) => {
+    validateValuesArray(values, 'calculateMax');
+    return processValue(values.length > 0 ? BigNumber.max(...values) : 0, config);
+};
+/**
+ * Calculates the mean of a list of values. An empty list returns 0.
+ * @param values The values.
+ * @param config How the result is processed.
+ * @returns The mean.
+ * @example
+ * calculateMean([1, 2, 4]); // 2.33
+ * @throws
+ * - INVALID_VALUE: if any of the given values isn't a finite number or BigNumber throws an error
+ * - INVALID_DECIMAL_PLACES: if the number of decimal places is invalid for any reason
+ * - INVALID_ROUNDING_MODE: if the rounding mode name is not supported
+ * - INVALID_TYPE: if the processing type is not supported
+ * - INVALID_VALUES_ARRAY: if the provided values arg is not a valid array
+ */
+export const calculateMean = (values, config) => {
+    validateValuesArray(values, 'calculateMean');
+    if (values.length > 0) {
+        return processValue(BigNumber.sum(...values).dividedBy(values.length), config);
+    }
+    return processValue(0, config);
+};
+/**
+ * Calculates the median of a list of values: the middle value, or the mean of the two middle
+ * values when the list has an even length. An empty list returns 0.
+ * @param values The values.
+ * @param config How the result is processed.
+ * @returns The median.
+ * @example
+ * calculateMedian([5, 1, 3]); // 3
+ * calculateMedian([4, 1, 3, 2]); // 2.5
+ * @throws
+ * - INVALID_VALUE: if any of the given values isn't a finite number or BigNumber throws an error
+ * - INVALID_DECIMAL_PLACES: if the number of decimal places is invalid for any reason
+ * - INVALID_ROUNDING_MODE: if the rounding mode name is not supported
+ * - INVALID_TYPE: if the processing type is not supported
+ * - INVALID_VALUES_ARRAY: if the provided values arg is not a valid array
+ */
+export const calculateMedian = (values, config) => {
+    validateValuesArray(values, 'calculateMedian');
+    if (values.length === 0) {
+        return processValue(0, config);
+    }
+    const half = Math.floor(values.length / 2);
+    const sorted = values.map(getBigNumber).sort(sortBigNumbers('asc'));
+    const middle = sorted[half];
+    const median = values.length % 2 === 1 ? middle : sorted[half - 1].plus(middle).dividedBy(2);
+    return processValue(median, config);
+};
+/*
+ * Percentage calculations
+ */
+/**
+ * Calculates the percentage a value changed by: positive when it increased, negative when it
+ * decreased, and 0 when it didn't change. The largest decrease is -100%, returned whenever the new
+ * value is 0 or less.
+ * @param oldValue The value before the change.
+ * @param newValue The value after the change.
+ * @param config How the result is processed.
+ * @returns The percentage change.
+ * @example
+ * calculatePercentageChange(100, 125); // 25
+ * calculatePercentageChange(100, 80); // -20
+ * calculatePercentageChange(100, 0); // -100
+ * @throws
+ * - INVALID_VALUE: if any of the given values isn't a finite number or BigNumber throws an error
+ * - INVALID_DECIMAL_PLACES: if the number of decimal places is invalid for any reason
+ * - INVALID_ROUNDING_MODE: if the rounding mode name is not supported
+ * - INVALID_TYPE: if the processing type is not supported
+ * - NEGATIVE_VALUE_NOT_ALLOWED: if the oldValue is not positive
+ */
+export const calculatePercentageChange = (oldValue, newValue, config) => {
+    const oldValueBN = getBigNumber(oldValue);
+    const newValueBN = getBigNumber(newValue);
+    validatePositiveValue(oldValueBN);
+    let change;
+    if (newValueBN.isGreaterThan(oldValueBN)) {
+        change = newValueBN.minus(oldValueBN).dividedBy(oldValueBN).times(100);
+    }
+    else if (oldValueBN.isGreaterThan(newValueBN)) {
+        change = newValueBN.isGreaterThan(0)
+            ? oldValueBN.minus(newValueBN).dividedBy(oldValueBN).times(100).negated()
+            : getBigNumber(-100);
+    }
+    else {
+        change = getBigNumber(0);
+    }
+    return processValue(change, config);
+};
+/**
+ * Changes a value by a percentage: a positive percentage increases it, and a negative one
+ * decreases it, to 0 at most.
+ * @param value The value to change.
+ * @param percentage The percentage to change it by.
+ * @param config How the result is processed.
+ * @returns The changed value.
+ * @example
+ * adjustByPercentage(100, 25); // 125
+ * adjustByPercentage(100, -10); // 90
+ * @throws
+ * - INVALID_VALUE: if any of the given values isn't a finite number or BigNumber throws an error
+ * - INVALID_DECIMAL_PLACES: if the number of decimal places is invalid for any reason
+ * - INVALID_ROUNDING_MODE: if the rounding mode name is not supported
+ * - INVALID_TYPE: if the processing type is not supported
+ * - NEGATIVE_VALUE_NOT_ALLOWED: if the value is not positive
+ */
+export const adjustByPercentage = (value, percentage, config) => {
+    const valueBN = getBigNumber(value);
+    const percentageBN = getBigNumber(percentage);
+    validatePositiveValue(valueBN);
+    let adjusted;
+    if (percentageBN.isGreaterThan(0)) {
+        adjusted = percentageBN.dividedBy(100).plus(1).times(valueBN);
+    }
+    else if (percentageBN.isLessThan(0)) {
+        adjusted = percentageBN.isGreaterThan(-100)
+            ? percentageBN.times(-1).dividedBy(100).minus(1).times(valueBN).times(-1)
+            : getBigNumber(0);
+    }
+    else {
+        adjusted = valueBN;
+    }
+    return processValue(adjusted, config);
+};
+/**
+ * Calculates what percentage of a total a value represents.
+ * @param value The part.
+ * @param total The total.
+ * @param config How the result is processed.
+ * @returns The percentage.
+ * @example
+ * calculatePercentageRepresentation(25, 200); // 12.5
+ * @throws
+ * - INVALID_VALUE: if any of the given values isn't a finite number or BigNumber throws an error
+ * - INVALID_DECIMAL_PLACES: if the number of decimal places is invalid for any reason
+ * - INVALID_ROUNDING_MODE: if the rounding mode name is not supported
+ * - INVALID_TYPE: if the processing type is not supported
+ * - NEGATIVE_VALUE_NOT_ALLOWED: if the value or total are not positive
+ */
+export const calculatePercentageRepresentation = (value, total, config) => {
+    const valueBN = getBigNumber(value);
+    const totalBN = getBigNumber(total);
+    validatePositiveValue(valueBN, true);
+    validatePositiveValue(totalBN);
+    return processValue(valueBN.times(100).dividedBy(totalBN), config);
+};
+/*
+ * Financial calculations
+ */
+/**
+ * Calculates the amount of an asset an exchange gives for a value at a rate, such as how much
+ * BTC 100 USDT buys at 65,000 USDT per BTC.
+ * @param value The amount being exchanged.
+ * @param rate The price of one unit of the asset received.
+ * @param config How the result is processed.
+ * @returns The amount received.
+ * @example
+ * calculateExchange(100, 65000, { decimalPlaces: 8 }); // 0.00153846
+ * @throws
+ * - INVALID_VALUE: if any of the given values isn't a finite number or BigNumber throws an error
+ * - INVALID_DECIMAL_PLACES: if the number of decimal places is invalid for any reason
+ * - INVALID_ROUNDING_MODE: if the rounding mode name is not supported
+ * - INVALID_TYPE: if the processing type is not supported
+ * - NEGATIVE_VALUE_NOT_ALLOWED: if the value or rate are not positive
+ */
+export const calculateExchange = (value, rate, config) => {
+    const valueBN = getBigNumber(value);
+    const rateBN = getBigNumber(rate);
+    validatePositiveValue(valueBN);
+    validatePositiveValue(rateBN);
+    return processValue(valueBN.dividedBy(rateBN), config);
+};
+/**
+ * Calculates the fee charged for an exchange, as a percentage of the value exchanged.
+ * @param value The amount being exchanged.
+ * @param feePercentage The fee, as a percentage.
+ * @param config How the result is processed.
+ * @returns The fee.
+ * @example
+ * calculateExchangeFee(1000, 0.1); // 1
+ * @throws
+ * - INVALID_VALUE: if any of the given values isn't a finite number or BigNumber throws an error
+ * - INVALID_DECIMAL_PLACES: if the number of decimal places is invalid for any reason
+ * - INVALID_ROUNDING_MODE: if the rounding mode name is not supported
+ * - INVALID_TYPE: if the processing type is not supported
+ * - NEGATIVE_VALUE_NOT_ALLOWED: if the value or feePercentage are not positive
+ */
+export const calculateExchangeFee = (value, feePercentage, config) => {
+    const valueBN = getBigNumber(value);
+    const feePercentageBN = getBigNumber(feePercentage);
+    validatePositiveValue(valueBN);
+    validatePositiveValue(feePercentageBN, true);
+    return processValue(feePercentageBN.times(valueBN).dividedBy(100), config);
+};
+/**
+ * Calculates the average entry price of a position bought in several trades, weighting each price
+ * by the amount bought. An empty list, or one whose amounts add up to 0, returns 0.
+ * @param trades The trades, each as a `[price, amount]` tuple.
+ * @param config How the result is processed.
+ * @returns The weighted average price.
+ * @example
+ * calculateWeightedEntry([[100, 2], [130, 1]]); // 110
+ * calculateWeightedEntry([]); // 0
+ * @throws
+ * - INVALID_VALUE: if any of the given values isn't a finite number or BigNumber throws an error
+ * - INVALID_DECIMAL_PLACES: if the number of decimal places is invalid for any reason
+ * - INVALID_ROUNDING_MODE: if the rounding mode name is not supported
+ * - INVALID_TYPE: if the processing type is not supported
+ * - INVALID_VALUES_ARRAY: if the provided values arg is not a valid array
+ */
+export const calculateWeightedEntry = (trades, config) => {
+    validateValuesArray(trades, 'calculateWeightedEntry');
+    if (trades.length === 0) {
+        return processValue(0, config);
+    }
+    let priceTimesShares = getBigNumber(0);
+    let totalShares = getBigNumber(0);
+    trades.forEach(([price, amount]) => {
+        const amountBN = getBigNumber(amount);
+        priceTimesShares = priceTimesShares.plus(getBigNumber(price).times(amountBN));
+        totalShares = totalShares.plus(amountBN);
+    });
+    if (totalShares.isZero()) {
+        return processValue(0, config);
+    }
+    return processValue(priceTimesShares.dividedBy(totalShares), config);
+};
+//# sourceMappingURL=calculations.js.map

package/dist/calculations/calculations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"calculations.js","sourceRoot":"","sources":["../../src/calculations/calculations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAEnD,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAE3F;;GAEG;AAEH;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,MAAyB,EACzB,MAAU,EACE,EAAE;IACd,mBAAmB,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC5C,OAAO,YAAY,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;AAChF,CAAC,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,MAAyB,EACzB,MAAU,EACE,EAAE;IACd,mBAAmB,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC5C,OAAO,YAAY,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;AAChF,CAAC,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,MAAyB,EACzB,MAAU,EACE,EAAE;IACd,mBAAmB,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC5C,OAAO,YAAY,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;AAChF,CAAC,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,MAAyB,EACzB,MAAU,EACE,EAAE;IACd,mBAAmB,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC7C,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,OAAO,YAAY,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;IACjF,CAAC;IACD,OAAO,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;AACjC,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,MAAyB,EACzB,MAAU,EACE,EAAE;IACd,mBAAmB,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAC/C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACjC,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC3C,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC;IACpE,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAe,CAAC;IAC1C,MAAM,MAAM,GACV,MAAM,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAE,MAAM,CAAC,IAAI,GAAG,CAAC,CAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAChG,OAAO,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AACtC,CAAC,CAAC;AAEF;;GAEG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CACvC,QAAyB,EACzB,QAAyB,EACzB,MAAU,EACE,EAAE;IACd,MAAM,UAAU,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC1C,MAAM,UAAU,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC1C,qBAAqB,CAAC,UAAU,CAAC,CAAC;IAElC,IAAI,MAAkB,CAAC;IACvB,IAAI,UAAU,CAAC,aAAa,CAAC,UAAU,CAAC,EAAE,CAAC;QACzC,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACzE,CAAC;SAAM,IAAI,UAAU,CAAC,aAAa,CAAC,UAAU,CAAC,EAAE,CAAC;QAChD,MAAM,GAAG,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC;YAClC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE;YACzE,CAAC,CAAC,YAAY,CAAC,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;SAAM,CAAC;QACN,MAAM,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AACtC,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,KAAsB,EACtB,UAA2B,EAC3B,MAAU,EACE,EAAE;IACd,MAAM,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IACpC,MAAM,YAAY,GAAG,YAAY,CAAC,UAAU,CAAC,CAAC;IAC9C,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAE/B,IAAI,QAAoB,CAAC;IACzB,IAAI,YAAY,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC;QAClC,QAAQ,GAAG,YAAY,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAChE,CAAC;SAAM,IAAI,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;QACtC,QAAQ,GAAG,YAAY,CAAC,aAAa,CAAC,CAAC,GAAG,CAAC;YACzC,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACzE,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IACtB,CAAC;SAAM,CAAC;QACN,QAAQ,GAAG,OAAO,CAAC;IACrB,CAAC;IACD,OAAO,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;AACxC,CAAC,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,CAC/C,KAAsB,EACtB,KAAsB,EACtB,MAAU,EACE,EAAE;IACd,MAAM,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IACpC,MAAM,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IACpC,qBAAqB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACrC,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAC/B,OAAO,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC;AACrE,CAAC,CAAC;AAEF;;GAEG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,KAAsB,EACtB,IAAqB,EACrB,MAAU,EACE,EAAE;IACd,MAAM,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IACpC,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAClC,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAC/B,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAC9B,OAAO,YAAY,CAAC,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;AACzD,CAAC,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAClC,KAAsB,EACtB,aAA8B,EAC9B,MAAU,EACE,EAAE;IACd,MAAM,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IACpC,MAAM,eAAe,GAAG,YAAY,CAAC,aAAa,CAAC,CAAC;IACpD,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAC/B,qBAAqB,CAAC,eAAe,EAAE,IAAI,CAAC,CAAC;IAC7C,OAAO,YAAY,CAAC,eAAe,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;AAC7E,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CACpC,MAA4C,EAC5C,MAAU,EACE,EAAE;IACd,mBAAmB,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;IACtD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACjC,CAAC;IACD,IAAI,gBAAgB,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;IACvC,IAAI,WAAW,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;IAClC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,EAAE;QACjC,MAAM,QAAQ,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;QACtC,gBAAgB,GAAG,gBAAgB,CAAC,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC9E,WAAW,GAAG,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;IACH,IAAI,WAAW,CAAC,MAAM,EAAE,EAAE,CAAC;QACzB,OAAO,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,YAAY,CAAC,gBAAgB,CAAC,SAAS,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,CAAC;AACvE,CAAC,CAAC","sourcesContent":["import { BigNumber } from '../shared/constants.js';\nimport type { IBigNumber, IBigNumberValue, IConfig, IOutput } from '../shared/types.js';\nimport { getBigNumber, processValue } from '../processing/processing.js';\nimport { sortBigNumbers } from '../utils/utils.js';\nimport { validatePositiveValue, validateValuesArray } from '../validations/validations.js';\n\n/*\n * Essential calculations\n */\n\n/**\n * Adds up a list of values. An empty list sums to 0.\n * @param values The values.\n * @param config How the result is processed.\n * @returns The sum.\n * @example\n * calculateSum([0.1, '0.2', 0.3]); // 0.6\n * calculateSum([0.1, 0.2], { type: 'string' }); // '0.3'\n * @throws\n * - INVALID_VALUE: if any of the given values isn't a finite number or BigNumber throws an error\n * - INVALID_DECIMAL_PLACES: if the number of decimal places is invalid for any reason\n * - INVALID_ROUNDING_MODE: if the rounding mode name is not supported\n * - INVALID_TYPE: if the processing type is not supported\n * - INVALID_VALUES_ARRAY: if the provided values arg is not a valid array\n */\nexport const calculateSum = <T extends Partial<IConfig>>(\n  values: IBigNumberValue[],\n  config?: T,\n): IOutput<T> => {\n  validateValuesArray(values, 'calculateSum');\n  return processValue(values.length > 0 ? BigNumber.sum(...values) : 0, config);\n};\n\n/**\n * Finds the smallest value in a list. An empty list returns 0.\n * @param values The values.\n * @param config How the result is processed.\n * @returns The smallest value.\n * @example\n * calculateMin([3, '1.5', 2]); // 1.5\n * @throws\n * - INVALID_VALUE: if any of the given values isn't a finite number or BigNumber throws an error\n * - INVALID_DECIMAL_PLACES: if the number of decimal places is invalid for any reason\n * - INVALID_ROUNDING_MODE: if the rounding mode name is not supported\n * - INVALID_TYPE: if the processing type is not supported\n * - INVALID_VALUES_ARRAY: if the provided values arg is not a valid array\n */\nexport const calculateMin = <T extends Partial<IConfig>>(\n  values: IBigNumberValue[],\n  config?: T,\n): IOutput<T> => {\n  validateValuesArray(values, 'calculateMin');\n  return processValue(values.length > 0 ? BigNumber.min(...values) : 0, config);\n};\n\n/**\n * Finds the largest value in a list. An empty list returns 0.\n * @param values The values.\n * @param config How the result is processed.\n * @returns The largest value.\n * @example\n * calculateMax([3, '1.5', 2]); // 3\n * @throws\n * - INVALID_VALUE: if any of the given values isn't a finite number or BigNumber throws an error\n * - INVALID_DECIMAL_PLACES: if the number of decimal places is invalid for any reason\n * - INVALID_ROUNDING_MODE: if the rounding mode name is not supported\n * - INVALID_TYPE: if the processing type is not supported\n * - INVALID_VALUES_ARRAY: if the provided values arg is not a valid array\n */\nexport const calculateMax = <T extends Partial<IConfig>>(\n  values: IBigNumberValue[],\n  config?: T,\n): IOutput<T> => {\n  validateValuesArray(values, 'calculateMax');\n  return processValue(values.length > 0 ? BigNumber.max(...values) : 0, config);\n};\n\n/**\n * Calculates the mean of a list of values. An empty list returns 0.\n * @param values The values.\n * @param config How the result is processed.\n * @returns The mean.\n * @example\n * calculateMean([1, 2, 4]); // 2.33\n * @throws\n * - INVALID_VALUE: if any of the given values isn't a finite number or BigNumber throws an error\n * - INVALID_DECIMAL_PLACES: if the number of decimal places is invalid for any reason\n * - INVALID_ROUNDING_MODE: if the rounding mode name is not supported\n * - INVALID_TYPE: if the processing type is not supported\n * - INVALID_VALUES_ARRAY: if the provided values arg is not a valid array\n */\nexport const calculateMean = <T extends Partial<IConfig>>(\n  values: IBigNumberValue[],\n  config?: T,\n): IOutput<T> => {\n  validateValuesArray(values, 'calculateMean');\n  if (values.length > 0) {\n    return processValue(BigNumber.sum(...values).dividedBy(values.length), config);\n  }\n  return processValue(0, config);\n};\n\n/**\n * Calculates the median of a list of values: the middle value, or the mean of the two middle\n * values when the list has an even length. An empty list returns 0.\n * @param values The values.\n * @param config How the result is processed.\n * @returns The median.\n * @example\n * calculateMedian([5, 1, 3]); // 3\n * calculateMedian([4, 1, 3, 2]); // 2.5\n * @throws\n * - INVALID_VALUE: if any of the given values isn't a finite number or BigNumber throws an error\n * - INVALID_DECIMAL_PLACES: if the number of decimal places is invalid for any reason\n * - INVALID_ROUNDING_MODE: if the rounding mode name is not supported\n * - INVALID_TYPE: if the processing type is not supported\n * - INVALID_VALUES_ARRAY: if the provided values arg is not a valid array\n */\nexport const calculateMedian = <T extends Partial<IConfig>>(\n  values: IBigNumberValue[],\n  config?: T,\n): IOutput<T> => {\n  validateValuesArray(values, 'calculateMedian');\n  if (values.length === 0) {\n    return processValue(0, config);\n  }\n  const half = Math.floor(values.length / 2);\n  const sorted = values.map(getBigNumber).sort(sortBigNumbers('asc'));\n  const middle = sorted[half] as IBigNumber;\n  const median =\n    values.length % 2 === 1 ? middle : (sorted[half - 1] as IBigNumber).plus(middle).dividedBy(2);\n  return processValue(median, config);\n};\n\n/*\n * Percentage calculations\n */\n\n/**\n * Calculates the percentage a value changed by: positive when it increased, negative when it\n * decreased, and 0 when it didn't change. The largest decrease is -100%, returned whenever the new\n * value is 0 or less.\n * @param oldValue The value before the change.\n * @param newValue The value after the change.\n * @param config How the result is processed.\n * @returns The percentage change.\n * @example\n * calculatePercentageChange(100, 125); // 25\n * calculatePercentageChange(100, 80); // -20\n * calculatePercentageChange(100, 0); // -100\n * @throws\n * - INVALID_VALUE: if any of the given values isn't a finite number or BigNumber throws an error\n * - INVALID_DECIMAL_PLACES: if the number of decimal places is invalid for any reason\n * - INVALID_ROUNDING_MODE: if the rounding mode name is not supported\n * - INVALID_TYPE: if the processing type is not supported\n * - NEGATIVE_VALUE_NOT_ALLOWED: if the oldValue is not positive\n */\nexport const calculatePercentageChange = <T extends Partial<IConfig>>(\n  oldValue: IBigNumberValue,\n  newValue: IBigNumberValue,\n  config?: T,\n): IOutput<T> => {\n  const oldValueBN = getBigNumber(oldValue);\n  const newValueBN = getBigNumber(newValue);\n  validatePositiveValue(oldValueBN);\n\n  let change: IBigNumber;\n  if (newValueBN.isGreaterThan(oldValueBN)) {\n    change = newValueBN.minus(oldValueBN).dividedBy(oldValueBN).times(100);\n  } else if (oldValueBN.isGreaterThan(newValueBN)) {\n    change = newValueBN.isGreaterThan(0)\n      ? oldValueBN.minus(newValueBN).dividedBy(oldValueBN).times(100).negated()\n      : getBigNumber(-100);\n  } else {\n    change = getBigNumber(0);\n  }\n  return processValue(change, config);\n};\n\n/**\n * Changes a value by a percentage: a positive percentage increases it, and a negative one\n * decreases it, to 0 at most.\n * @param value The value to change.\n * @param percentage The percentage to change it by.\n * @param config How the result is processed.\n * @returns The changed value.\n * @example\n * adjustByPercentage(100, 25); // 125\n * adjustByPercentage(100, -10); // 90\n * @throws\n * - INVALID_VALUE: if any of the given values isn't a finite number or BigNumber throws an error\n * - INVALID_DECIMAL_PLACES: if the number of decimal places is invalid for any reason\n * - INVALID_ROUNDING_MODE: if the rounding mode name is not supported\n * - INVALID_TYPE: if the processing type is not supported\n * - NEGATIVE_VALUE_NOT_ALLOWED: if the value is not positive\n */\nexport const adjustByPercentage = <T extends Partial<IConfig>>(\n  value: IBigNumberValue,\n  percentage: IBigNumberValue,\n  config?: T,\n): IOutput<T> => {\n  const valueBN = getBigNumber(value);\n  const percentageBN = getBigNumber(percentage);\n  validatePositiveValue(valueBN);\n\n  let adjusted: IBigNumber;\n  if (percentageBN.isGreaterThan(0)) {\n    adjusted = percentageBN.dividedBy(100).plus(1).times(valueBN);\n  } else if (percentageBN.isLessThan(0)) {\n    adjusted = percentageBN.isGreaterThan(-100)\n      ? percentageBN.times(-1).dividedBy(100).minus(1).times(valueBN).times(-1)\n      : getBigNumber(0);\n  } else {\n    adjusted = valueBN;\n  }\n  return processValue(adjusted, config);\n};\n\n/**\n * Calculates what percentage of a total a value represents.\n * @param value The part.\n * @param total The total.\n * @param config How the result is processed.\n * @returns The percentage.\n * @example\n * calculatePercentageRepresentation(25, 200); // 12.5\n * @throws\n * - INVALID_VALUE: if any of the given values isn't a finite number or BigNumber throws an error\n * - INVALID_DECIMAL_PLACES: if the number of decimal places is invalid for any reason\n * - INVALID_ROUNDING_MODE: if the rounding mode name is not supported\n * - INVALID_TYPE: if the processing type is not supported\n * - NEGATIVE_VALUE_NOT_ALLOWED: if the value or total are not positive\n */\nexport const calculatePercentageRepresentation = <T extends Partial<IConfig>>(\n  value: IBigNumberValue,\n  total: IBigNumberValue,\n  config?: T,\n): IOutput<T> => {\n  const valueBN = getBigNumber(value);\n  const totalBN = getBigNumber(total);\n  validatePositiveValue(valueBN, true);\n  validatePositiveValue(totalBN);\n  return processValue(valueBN.times(100).dividedBy(totalBN), config);\n};\n\n/*\n * Financial calculations\n */\n\n/**\n * Calculates the amount of an asset an exchange gives for a value at a rate, such as how much\n * BTC 100 USDT buys at 65,000 USDT per BTC.\n * @param value The amount being exchanged.\n * @param rate The price of one unit of the asset received.\n * @param config How the result is processed.\n * @returns The amount received.\n * @example\n * calculateExchange(100, 65000, { decimalPlaces: 8 }); // 0.00153846\n * @throws\n * - INVALID_VALUE: if any of the given values isn't a finite number or BigNumber throws an error\n * - INVALID_DECIMAL_PLACES: if the number of decimal places is invalid for any reason\n * - INVALID_ROUNDING_MODE: if the rounding mode name is not supported\n * - INVALID_TYPE: if the processing type is not supported\n * - NEGATIVE_VALUE_NOT_ALLOWED: if the value or rate are not positive\n */\nexport const calculateExchange = <T extends Partial<IConfig>>(\n  value: IBigNumberValue,\n  rate: IBigNumberValue,\n  config?: T,\n): IOutput<T> => {\n  const valueBN = getBigNumber(value);\n  const rateBN = getBigNumber(rate);\n  validatePositiveValue(valueBN);\n  validatePositiveValue(rateBN);\n  return processValue(valueBN.dividedBy(rateBN), config);\n};\n\n/**\n * Calculates the fee charged for an exchange, as a percentage of the value exchanged.\n * @param value The amount being exchanged.\n * @param feePercentage The fee, as a percentage.\n * @param config How the result is processed.\n * @returns The fee.\n * @example\n * calculateExchangeFee(1000, 0.1); // 1\n * @throws\n * - INVALID_VALUE: if any of the given values isn't a finite number or BigNumber throws an error\n * - INVALID_DECIMAL_PLACES: if the number of decimal places is invalid for any reason\n * - INVALID_ROUNDING_MODE: if the rounding mode name is not supported\n * - INVALID_TYPE: if the processing type is not supported\n * - NEGATIVE_VALUE_NOT_ALLOWED: if the value or feePercentage are not positive\n */\nexport const calculateExchangeFee = <T extends Partial<IConfig>>(\n  value: IBigNumberValue,\n  feePercentage: IBigNumberValue,\n  config?: T,\n): IOutput<T> => {\n  const valueBN = getBigNumber(value);\n  const feePercentageBN = getBigNumber(feePercentage);\n  validatePositiveValue(valueBN);\n  validatePositiveValue(feePercentageBN, true);\n  return processValue(feePercentageBN.times(valueBN).dividedBy(100), config);\n};\n\n/**\n * Calculates the average entry price of a position bought in several trades, weighting each price\n * by the amount bought. An empty list, or one whose amounts add up to 0, returns 0.\n * @param trades The trades, each as a `[price, amount]` tuple.\n * @param config How the result is processed.\n * @returns The weighted average price.\n * @example\n * calculateWeightedEntry([[100, 2], [130, 1]]); // 110\n * calculateWeightedEntry([]); // 0\n * @throws\n * - INVALID_VALUE: if any of the given values isn't a finite number or BigNumber throws an error\n * - INVALID_DECIMAL_PLACES: if the number of decimal places is invalid for any reason\n * - INVALID_ROUNDING_MODE: if the rounding mode name is not supported\n * - INVALID_TYPE: if the processing type is not supported\n * - INVALID_VALUES_ARRAY: if the provided values arg is not a valid array\n */\nexport const calculateWeightedEntry = <T extends Partial<IConfig>>(\n  trades: [IBigNumberValue, IBigNumberValue][],\n  config?: T,\n): IOutput<T> => {\n  validateValuesArray(trades, 'calculateWeightedEntry');\n  if (trades.length === 0) {\n    return processValue(0, config);\n  }\n  let priceTimesShares = getBigNumber(0);\n  let totalShares = getBigNumber(0);\n  trades.forEach(([price, amount]) => {\n    const amountBN = getBigNumber(amount);\n    priceTimesShares = priceTimesShares.plus(getBigNumber(price).times(amountBN));\n    totalShares = totalShares.plus(amountBN);\n  });\n  if (totalShares.isZero()) {\n    return processValue(0, config);\n  }\n  return processValue(priceTimesShares.dividedBy(totalShares), config);\n};\n"]}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export type { IBigNumber, IBigNumberFormat, IBigNumberRoundingMode, IBigNumberRoundingModeName, IBigNumberToType, IBigNumberValue, IConfig, IOutput, IType, } from './shared/types.js';
+export { BigNumber } from './shared/constants.js';
+export { ERRORS } from './shared/errors.js';
+export { getBigNumber, isBigNumber, isFloat, isInteger, isNumber, prettifyValue, processValue, } from './processing/processing.js';
+export { adjustByPercentage, calculateExchange, calculateExchangeFee, calculateMax, calculateMean, calculateMedian, calculateMin, calculatePercentageChange, calculatePercentageRepresentation, calculateSum, calculateWeightedEntry, } from './calculations/calculations.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+// constructor
+export { BigNumber } from './shared/constants.js';
+// error codes
+export { ERRORS } from './shared/errors.js';
+// value processors and type checks
+export { getBigNumber, isBigNumber, isFloat, isInteger, isNumber, prettifyValue, processValue, } from './processing/processing.js';
+// calculations
+export { adjustByPercentage, calculateExchange, calculateExchangeFee, calculateMax, calculateMean, calculateMedian, calculateMin, calculatePercentageChange, calculatePercentageRepresentation, calculateSum, calculateWeightedEntry, } from './calculations/calculations.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,cAAc;AACd,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD,cAAc;AACd,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE5C,mCAAmC;AACnC,OAAO,EACL,YAAY,EACZ,WAAW,EACX,OAAO,EACP,SAAS,EACT,QAAQ,EACR,aAAa,EACb,YAAY,GACb,MAAM,4BAA4B,CAAC;AAEpC,eAAe;AACf,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,EACpB,YAAY,EACZ,aAAa,EACb,eAAe,EACf,YAAY,EACZ,yBAAyB,EACzB,iCAAiC,EACjC,YAAY,EACZ,sBAAsB,GACvB,MAAM,gCAAgC,CAAC","sourcesContent":["// types\nexport type {\n  IBigNumber,\n  IBigNumberFormat,\n  IBigNumberRoundingMode,\n  IBigNumberRoundingModeName,\n  IBigNumberToType,\n  IBigNumberValue,\n  IConfig,\n  IOutput,\n  IType,\n} from './shared/types.js';\n\n// constructor\nexport { BigNumber } from './shared/constants.js';\n\n// error codes\nexport { ERRORS } from './shared/errors.js';\n\n// value processors and type checks\nexport {\n  getBigNumber,\n  isBigNumber,\n  isFloat,\n  isInteger,\n  isNumber,\n  prettifyValue,\n  processValue,\n} from './processing/processing.js';\n\n// calculations\nexport {\n  adjustByPercentage,\n  calculateExchange,\n  calculateExchangeFee,\n  calculateMax,\n  calculateMean,\n  calculateMedian,\n  calculateMin,\n  calculatePercentageChange,\n  calculatePercentageRepresentation,\n  calculateSum,\n  calculateWeightedEntry,\n} from './calculations/calculations.js';\n"]}