Distributes the given total number in desired weights.
npm install allocationDistributes a given value based on shares. When the sum of the shares equals 100, it functions akin to percentages.
| Supported | Exact Calculation |
| ------------------------- | ----------------- |
| Native JS floating points | No |
| bignumber.js | Yes |
| decimal.js | Yes |
``ts
import { distribute } from "allocation";
const result = distribute(200, [45, 55]); // [90, 110]
`
`ts
import { distribute } from "allocation";
import { BigNumber } from "bignumber.js";
const result = distribute(BigNumber(200), [45, 55]); // [BigNumber(90), BigNumber(110)]
`
Floating point numbers (JS native numbers) are not suitable for exact calculations.
See the below example:
`ts`
const shares = [49.9, 49.9, 0.2];
const result = distribute(100, shares); // [49.9, 49.9, 0.20000000000000284]
Sometimes when the results are rounded they seem exact, but they are not, different inputs may result in inexact calculations even when rounding.
`ts`
const shares = [49.9, 49.9, 0.2];
const result = distribute(100, shares, { scale: 2 }); // [49.9, 49.9, 0.2] WARNING: Seems OK, but it is not.
Use external numeric libraries where exact calculations are needed. (i.e. monetary calculations)
`ts
import { BigNumber } from "bignumber.js";
const shares = [49.9, 49.9, 0.2];
const result = distribute(BigNumber(100), shares); // [BigNumber(49.9), BigNumber(49.9), BigNumber(0.2)]
`
distribute(value, shares, { scale }): Numeric[]
This function distributes a given BigNumber.js or Decimal.js value based on shares.
When the sum of the shares equals 100, it functions akin to percentages.
#### Parameters
| Name | Type | Description |
| :------- | :--------------------------------------------- | :--------------------------------------------------------- |
| value | Numeric | is the total value to distribute. |shares
| | (number \| Numeric)[] | is shares (weights) to distribute. |scale
| | number` | Number of digits after decimal point to round the results. |