Hidden

Overview

Finds the most common value (mode) in an AmountArray by counting the frequency of each amount value.

amountArray.mode();

Features

• Returns a new Amount instance with the most frequent value
• Requires all amounts to have the same currency
• Maintains immutability - original array remains unchanged
• Counts frequencies based on amount values
• Throws error for empty arrays or mixed currencies
• Simple and intuitive API
• Comprehensive testing

Arguments

Arg	Type	Default Value	Required
No arguments required

Usage

From an AmountArray instance, use the mode() method to find the most common value in the array.

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

const amounts = new AmountArray(
  amount(100, 'USD'),
  amount(200, 'USD'),
  amount(100, 'USD'), // Most frequent
  amount(300, 'USD'),
  amount(100, 'USD')  // Most frequent (appears 3 times)
);

const result = amounts.mode();

console.log(result); // Results in Amount instance with value 100 USD

It requires all amounts to have the same currency:

const validAmounts = new AmountArray(
  amount(50, 'EUR'),
  amount(75, 'EUR'),
  amount(50, 'EUR'), // Most frequent
  amount(25, 'EUR'),
  amount(50, 'EUR')  // Most frequent (appears 3 times)
);

const result = validAmounts.mode();

console.log(result); // Results in Amount instance with value 50 EUR

It throws an error for mixed currencies:

const mixedAmounts = new AmountArray(
  amount(100, 'USD'),
  amount(100, 'EUR') // Different currency
);

// This will throw: "All amounts must have the same currency for mode operation."
const result = mixedAmounts.mode();

It throws an error for empty arrays:

const emptyArray = new AmountArray();

// This will throw: "Cannot find mode of an empty AmountArray."
const result = emptyArray.mode();

Works with single occurrence values:

const uniqueAmounts = new AmountArray(
  amount(100, 'GBP'),
  amount(200, 'GBP'),
  amount(300, 'GBP')
);

const result = uniqueAmounts.mode(); // Returns the first value (100 GBP)

Examples

Imagine a scenario in an e-commerce application. Based on store settings, you need to find the most common installment amount to present at checkout.

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

// Customer's shopping cart total
const cartTotal = amount(1000, 'USD');

// Split into 6 installments using split() method
const installments = cartTotal.split(6);

console.log(installments); // AmountArray with 6 installment amounts

// Store setting: Standardize installments to the most common value
// Find the most frequent installment amount for consistency
const commonInstallment = installments.mode();

console.log(`Most common installment: ${commonInstallment}`);
// Use this value to standardize all installments for simpler processing