Dinero.js
Dinero.js version

# allocate

`Dinero<TAmount>[]`

Distribute the amount of a Dinero object across a list of ratios.

Monetary values have indivisible units, meaning you can't always exactly split them. With `allocate`, you can split a monetary amount then distribute the remainder as evenly as possible.

You can use percentage or ratio style for `ratios`: `[25, 75]` and `[1, 3]` do the same thing. You can also pass zero ratios (such as `[0, 50, 50]`). If there's a remainder to distribute, zero ratios are skipped and return a Dinero object with amount zero.

If you need to use fractional ratios, you shouldn't use floats, but scaled amounts instead. For example, instead of passing `[50.5, 49.5]`, you should pass `[{ amount: 505, scale: 1 }, { amount: 495, scale: 1 }]`. When using scaled amounts, the function converts the returned objects to the safest scale.

All ratios must be positive, and you can't only pass zero ratios.

NameTypeDescriptionRequired
`dineroObject``Dinero<TAmount>`

The Dinero object to allocate from.

Yes
`ratios``Array<ScaledAmount<TAmount> | TAmount>`

The ratios to allocate the amount to.

Yes

``````import { dinero, allocate } from 'dinero.js';
import { USD } from '@dinero.js/currencies';

const d = dinero({ amount: 500, currency: USD });

const [d1, d2] = allocate(d, [50, 50]);

d1; // a Dinero object with amount 250
d2; // a Dinero object with amount 250
``````

``````import { dinero, allocate } from 'dinero.js';
import { USD } from '@dinero.js/currencies';

const d = dinero({ amount: 100, currency: USD });

const [d1, d2] = allocate(d, [1, 3]);

d1; // a Dinero object with amount 25
d2; // a Dinero object with amount 75
``````

### Copy linkDistribute as fairly as possible

``````import { dinero, allocate } from 'dinero.js';
import { USD } from '@dinero.js/currencies';

const d = dinero({ amount: 1003, currency: USD });

const [d1, d2] = allocate(d, [50, 50]);

d1; // a Dinero object with amount 502
d2; // a Dinero object with amount 501
``````

``````import { dinero, allocate } from 'dinero.js';
import { USD } from '@dinero.js/currencies';

const d = dinero({ amount: 1003, currency: USD });

const [d1, d2, d3] = allocate(d, [0, 50, 50]);

d1; // a Dinero object with amount 0
d2; // a Dinero object with amount 502
d3; // a Dinero object with amount 501
``````

### Copy linkUse scaled ratios and convert to the safest scale

``````import { dinero, allocate } from 'dinero.js';
import { USD } from '@dinero.js/currencies';

const ratios = [
{ amount: 505, scale: 1 },
{ amount: 495, scale: 1 },
]; // translates to ratios 50.5 and 49.5
const d = dinero({ amount: 100, currency: USD });

const [d1, d2] = allocate(d, ratios);

d1; // a Dinero object with amount 505 and scale 3
d2; // a Dinero object with amount 495 and scale 3
``````