ozum / allocation

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.