Number Utils

Overview

The NumberUtils module provides a collection of helper functions for performing common number-related operations in your server-side JavaScript code. It simplifies tasks like formatting, rounding, parsing, and validating numeric values-ensuring consistency and reducing boilerplate across your application.

Whether you're working with prices, percentages, calculations, or user input, the NumberUtils module offers reliable utilities for handling numbers with precision and ease.

Note: The NumberUtils module is globally available via kd.numberUtils

Key Features

1. Rounding & Precision: Round numbers to a fixed number of decimal places, or apply custom precision rules.
2. Formatting: Convert numbers into formatted strings for currency, percentages, or readable output.
3. Parsing: Safely parse strings into numbers, with optional fallback defaults.
4. Validation: Check if a value is a valid number or falls within a specific numeric range.

Example Use Cases

1. Rounding prices or totals for display or calculation
2. Validating numeric input in forms or APIs
3. Formatting numbers for invoices, dashboards, or reports
4. Ensuring numeric values stay within expected bounds

The NumberUtils module is lightweight and designed to be used wherever numeric logic is needed in your server-side code.

Methods

generateId()

Generates a random unique ID string based on the current timestamp and a random number.

1. Parameters: None
2. Returns (String): Returns a string representing a unique identifier.
3. Example:

var uniqueId = kd.numberUtils.generateId();
// Returns something like: "a7npor1686924719zll"

formatQuantity(value)

Formats a number as a quantity with thousands separators and no decimal places.

1. Parameters
   1. value (Number, required): The number to format as a quantity.
2. Returns (String): Returns a string representation of the number with thousands separators and no decimal places, or an empty string if the input is invalid.

var formattedQuantity = kd.numberUtils.formatQuantity(1234567);
// Returns: "1,234,567"

var invalid = kd.numberUtils.formatQuantity(null);
// Returns: ""

toCurrency(value, opts)

Formats a number as a currency value with dollar sign, thousands separators, and appropriate handling of negative values.

1. Parameters
   1. value (Number, required): The number to format as currency.
   2. opts (Object, optional): Formatting options with the following properties
      1. minimumFractionDigits (Number, optional): The minimum number of decimal places to show. Defaults to 2.
2. Returns (String): A string representation of the number as currency with a dollar sign and thousands separators, or an empty string if the input is invalid.
3. Example

var price = kd.numberUtils.toCurrency(1234.56);
// Returns: $1,234.56

const negativePrice = kd.numberUtils.toCurrency(-1234.56);
// Returns: ($1,234.56)

var customDecimals = kd.numberUtils.toCurrency(1234.5, { minimumFractionDigits: 3 });
// Returns: $1,234.500

const invalid = kd.numberUtils.toCurrency(null);
// Returns: ""

toNumber(value, decimals)

Converts a value to a number with the specified number of decimal places.

1. Parameters
   1. value (Any, required): The value to convert to a number.
   2. decimals (Number, optional): The number of decimal places.
2. Returns (String): Returns the value converted to a number with the specified decimal places.
3. Example

var number = kd.numberUtils.toNumber("123.456", 2);
// Returns: 123.46 (rounded to 2 decimal places)

toCurrencyNumber(value)

Rounds a number to two decimal places for currency calculations, ensuring proper handling of floating-point precision issues.

1. Parameters
   1. value (Number, required): The number to round for currency calculations.
2. Returns (String): A string representation of the number rounded to exactly two decimal places, or an empty string if the input is invalid.
3. Example

var rounded = kd.numberUtils.toCurrencyNumber(1.9999999999);
// Returns: "1.99"

var wholeNumber = kd.numberUtils.toCurrencyNumber(2);
// Returns: "2.00"

var invalid = kd.numberUtils.toCurrencyNumber(null);
// Returns: ""