Allocation

Distributes 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 |

Usage with Floating Point Numbers

import { distribute } from "allocation";

const result = distribute(200, [45, 55]); // [90, 110]

Usage with External Libraries

import { distribute } from "allocation";
import { BigNumber } from "bignumber.js";

const result = distribute(BigNumber(200), [45, 55]); // [BigNumber(90), BigNumber(110)]

Exact Calculations

Floating point numbers (JS native numbers) are not suitable for exact calculations.

See the below example:

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.

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)

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)]

API

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. |