Struggling to understand the allocate function

[JayyWalker]

The upgrade to 2.0.0 requires us to replace Dinero.divide with allocate. With 1.8.1, I used divide to split an amount into 12 in order to represent a monthly payment for 12 months. However, this doesn't seem so straight forward with the allocate function.

1.8.1

const d1 = Dinero({ amount: 51998, currency: "GBP" })

const monthly = d1.divide(12) 

console.log(monthly.toUnit()) // Results in: 43.33

2.0.0

const d1 = dinero({ amount: 51998, currency: GBP })

const allocation = allocate(d1, [1, 12])

const values = allocation.map((allot) => toUnit(allot))

console.log(values)  // Results in: [ 40, 479.98 ]

However, the result of this is not the result I'm after. How can I distribute the value into 12?

[sarahdayan]

Hey @JayyWalker!

When using allocate, you're splitting the value into "buckets". If you do CSS, you can see it as CSS Grids, when you distribute grid-template-columns (1fr 1fr 2fr ...).

If you need to split your object into twelve equal parts, your code should look like this:

const d1 = dinero({ amount: 51998, currency: GBP });

const allocation = allocate(d1, [1, 1, 1, 1, 1, 1, 1, 1, 1, 1]); // an array of 12 ratios of value `1` (even distribution)
const values = allocation.map((allocated) => toUnit(allocated));

console.log(values); // [ 52, 52, 52, 52, 52, 52, 52, 52, 51.99, 51.99 ]

As you can see, allocate split the value into twelve parts, trying as much as possible to make them equal. This is much more precise than dividing, which would return an imprecise, non finite figure.

The long list of ratios is a bit unsightly, so you can refactor to:

const ratios = Array.from({ length: 12 }).fill(1);
const allocation = allocate(d1, ratios);

[JayyWalker]

Ah, lifesaver! That's perfect, thank you ever so much.

The way the documentation mentioned ratios I immediately assumed it to be something like 1:3 or 3:4 etc. So instead it works more like portions?

[sarahdayan]

Yes, your assumption was correct. A ratio is about proportions, it indicates how many times one number contains another. When you specify [3, 1], it means the first share contains three times the second one. With a Dinero object of 100, you would get 75 and 25 (25*3 = 75).

Does this make sense?

[herman-axiology]

I would like to raise an issue with this approach.

First of all, I do understand the reasoning and approach of using allocate to achieve "division" and I think it is a right approach semantically.

Though its not a safe and viable solution. More so if using bigints.

Suppose we are using large values, perhaps big exponents for our currencies and or ratios. It is very dangerous and sometimes impposible to create arrays of such large length. For example suppose calculation of price per unit:

const total = dinero({ amount: Number.MAX_SAFE_INTEGER, currency: {code: 'USD', exponent: 2 } }) // Number.MAX_SAFE_INTEGER = 9007199254740991 
const ratios = Array.from({ length: Number.MAX_SAFE_INTEGER }).fill(1); // <-- will fail because max array length can only be 4294967295

const [unitPrice] = allocate(total, ratios) // not even possible

Even for values that would "fit" in allowed limits, it is not a memory friendly calculation.

[NateAGeek]

Can we not add back in shortcuts or helper functions that will support more, and this is my opinion, common divide?

[jasongitmail]

Is there a workaround to divide by an arbitrary number that could be a decimal?

I've tried to multiply by a fraction, but this only works if the divisor is an integer. When it's a decimal, some error occurs within dinero and I don't receive any output beyond that point.

For example, if num2 is an integer, I get an accurate result. If it's a decimal, I get no result and this won't console log.

dineroResult = multiply(dinero1, 1 / num2);
console.log('divide result:', dineroResult);

Seem very limiting to not support divide() in v2.