Array Metrics Utilities

The Array Metrics utilities provide calculation tools for performing arithmetic operations like sum, average, or difference on arrays of objects. These functions support dot notation for accessing nested object fields and are particularly useful in transforming structured datasets.

sumByField

The sumByField function calculates the total sum of a numeric field across all items in an array.

Function Signature

function sumByField<T extends GenericObject>(data: Maybe<T[]>, field: NumericDotKey<T>, roundTo?: number): number

Parameters

• data (T[] | undefined): The array of objects to process.
• field (NumericDotKey<T>): The field to sum (supports dot notation for nested properties).
• roundTo (number): Number of decimal places to round to. Defaults to 2.

Returns

• number: The rounded total sum of all field values.

Example

averageByField

The averageByField function calculates the average of a numeric field across all items.

Function Signature

function averageByField<T extends GenericObject>(data: Maybe<T[]>, field: NumericDotKey<T>, roundTo?: number): number

Parameters

• data (T[] | undefined): The array of objects to process.
• field (NumericDotKey<T>): The field to average (supports nested properties).
• roundTo (number): Number of decimal places to round to. Defaults to 2.

Returns

• number: The rounded average value.

Example

sumFieldDifference

The sumFieldDifference function calculates the sum of differences between two numeric fields for each item.

Function Signature

function sumFieldDifference<T extends GenericObject, P extends NumericDotKey<T>>(data: Maybe<T[]>, first: P, second: P, roundTo?: number): number

Parameters

• data (T[] | undefined): The array of objects to process.
• first (P): The field to subtract from (minuend).
• second (P): The field to subtract (subtrahend).
• roundTo (number): Number of decimal places to round the result. Defaults to 2.

Returns

• number: The total sum of differences between the fields.

Example

groupAndSumByField

The groupAndSumByField function groups an array of objects by a field and calculates the sum of another numeric field within each group.

Internally uses splitArrayByProperty

Function Signature

function groupAndSumByField<T extends GenericObject>(
    data: Maybe<T[]>,
    groupBy: NestedPrimitiveKey<T>,
    sumBy: NumericDotKey<T>,
    roundTo?: number
): Array<Record<string, number>>

Parameters

• data (T[] | undefined): The array to group and process.
• groupBy (NestedPrimitiveKey<T>): The field to group by (supports nested keys).
• sumBy (NumericDotKey<T>): The field to sum for each group.
• roundTo (number): Decimal precision. Defaults to 2.

Returns

• Array<Record<string, number>>: An array of records with group key as property and sum as value.

Example

groupAndAverageByField

The groupAndAverageByField function groups an array of objects by a field and calculates the average of another numeric field for each group.

Internally uses splitArrayByProperty

Function Signature

function groupAndAverageByField<T extends GenericObject>(
    data: Maybe<T[]>,
    groupBy: NestedPrimitiveKey<T>,
    averageBy: NumericDotKey<T>,
    roundTo?: number
): Array<Record<string, number>>

Parameters

• data (T[] | undefined): The array to group and process.
• groupBy (NestedPrimitiveKey<T>): The field to group by (supports dot notation).
• averageBy (NumericDotKey<T>): The field to average per group.
• roundTo (number): Decimal precision. Defaults to 2.

Returns

• Array<Record<string, number>>: An array of records with group key and averaged value.

Example

Key Features

• Dot Notation Support: All utilities support nested fields using dot-notation paths like meta.sales.total
• Fallback-Safe: Handles undefined arrays and missing fields gracefully
• Consistent Precision: All results are optionally rounded with customizable precision
• Composable: Works in tandem with utilities like splitArrayByProperty for more complex data processing

Aliases