Hidden

Overview

Allocates an amount according to a list of ratios, distributing the total proportionally. Perfect for proportional payments, cost distribution, and revenue sharing.

amount.allocate(/ratios/);

Features

• Returns an array of Amount instances
• Distributes amount proportionally based on ratios
• Preserves the original currency in all allocated amounts
• Handles remainder distribution to maintain exact totals
• Supports any ratio values (percentages, weights, etc.)
• Maintains immutability - original instance remains unchanged
• Perfect for financial allocations and distributions
• Comprehensive testing

Arguments

Arg	Type	Default Value	Required
ratios	number[]	-	Yes

Usage

From an Amount instance, use the allocate() method to distribute the amount according to specified ratios.

import { amount } from '@inpulse-ui/utils';

const totalAmount = amount(100, 'USD');
const allocated = totalAmount.allocate([1, 2, 1]); // Ratios of 1:2:1

console.log(allocated[0].getValue()); // 25 (1/4 of 100)
console.log(allocated[1].getValue()); // 50 (2/4 of 100)
console.log(allocated[2].getValue()); // 25 (1/4 of 100)

Using percentage-based ratios:

const revenue = amount(1000, 'USD');
const allocated = revenue.allocate([60, 30, 10]); // 60%, 30%, 10%

console.log(allocated[0].format()); // $600.00
console.log(allocated[1].format()); // $300.00
console.log(allocated[2].format()); // $100.00

Handling remainder distribution:

// When exact division isn't possible, remainder is distributed
const amount99 = amount(99, 'USD');
const allocated = amount99.allocate([1, 1, 1]); // Split into 3 equal parts

console.log(allocated[0].getValue()); // 33 (gets remainder)
console.log(allocated[1].getValue()); // 33
console.log(allocated[2].getValue()); // 33

// Total is always preserved
const sum = allocated.reduce((total, part) => total.add(part), amount(0, 'USD'));
console.log(sum.getValue()); // 99 (original amount preserved)

Examples

Subscription billing - allocating monthly revenue between different revenue streams:

import { amount } from '@inpulse-ui/utils';

// Monthly subscription revenue
const monthlyRevenue = amount(50000, 'USD');

// Allocation based on subscription tiers: Basic (50%), Pro (35%), Enterprise (15%)
const tierAllocations = monthlyRevenue.allocate([50, 35, 15]);

const revenueBreakdown = {
  basic: tierAllocations[0],
  pro: tierAllocations[1],
  enterprise: tierAllocations[2]
};

// Display revenue breakdown
console.log('Monthly Revenue Breakdown:');
console.log(`Basic Tier: ${revenueBreakdown.basic.format()}`);       // $25,000.00
console.log(`Pro Tier: ${revenueBreakdown.pro.format()}`);           // $17,500.00
console.log(`Enterprise Tier: ${revenueBreakdown.enterprise.format()}`); // $7,500.00

// Calculate commission for sales team (10% of each tier)
const commissions = [
  revenueBreakdown.basic.multiply(0.1),
  revenueBreakdown.pro.multiply(0.1),
  revenueBreakdown.enterprise.multiply(0.1)
];

const totalCommission = commissions.reduce((sum, commission) => sum.add(commission), amount(0, 'USD'));
console.log(`Total Sales Commission: ${totalCommission.format()}`); // $5,000.00

Revenue sharing between partners:

const monthlyRevenue = amount(15000, 'USD');
const partnerShares = monthlyRevenue.allocate([5, 3, 2]); // 50%, 30%, 20%

console.log(`Partner A: ${partnerShares[0].format()}`); // Partner A: $7,500.00
console.log(`Partner B: ${partnerShares[1].format()}`); // Partner B: $4,500.00
console.log(`Partner C: ${partnerShares[2].format()}`); // Partner C: $3,000.00

// Verify total is preserved
const total = partnerShares.reduce((sum, share) => sum.add(share), amount(0, 'USD'));
console.log(`Total: ${total.format()}`); // Total: $15,000.00

Cost distribution with different weights:

const projectCost = amount(5000, 'EUR');
const departmentWeights = [40, 35, 15, 10]; // Based on department sizes
const costAllocation = projectCost.allocate(departmentWeights);

departmentWeights.forEach((weight, index) => {
  const percentage = (weight / departmentWeights.reduce((a, b) => a + b, 0)) * 100;
  console.log(`Department ${index + 1}: ${costAllocation[index].format()} (${percentage}%)`);
});
// Department 1: €2,000.00 (40%)
// Department 2: €1,750.00 (35%)
// Department 3: €750.00 (15%)
// Department 4: €500.00 (10%)

Investment portfolio allocation:

const investmentAmount = amount(10000, 'USD');
const assetAllocation = investmentAmount.allocate([6, 3, 1]); // 60% stocks, 30% bonds, 10% cash

const allocatedAmounts = {
  stocks: assetAllocation[0],
  bonds: assetAllocation[1],
  cash: assetAllocation[2]
};

console.log(`Stocks: ${allocatedAmounts.stocks.format()}`);   // Stocks: $6,000.00
console.log(`Bonds: ${allocatedAmounts.bonds.format()}`);     // Bonds: $3,000.00
console.log(`Cash: ${allocatedAmounts.cash.format()}`);       // Cash: $1,000.00