nhb-toolbox/dist/dts/array/calc.d.ts

A versatile collection of smart, efficient, and reusable utility functions, classes and types for everyday development needs.

import type { GenericObject, NestedPrimitiveKey, NumericDotKey } from '../object/types';
import type { Maybe } from '../types/index';
/**
 * * Calculates the sum of differences between two numeric fields for each item in the array.
 *
 * @param data - The array of objects to process.
 * @param first - The field name to subtract **from** (minuend), supports nested dot notation.
 * @param second - The field name to subtract (subtrahend), supports nested dot notation.
 * @param roundTo - Decimal places to round the result to. Defaults to 2.
 * @returns The total sum of differences between the two fields across all items.
 *
 * @example
 * sumFieldDifference([{ buy: 10, sell: 3 }, { buy: 8, sell: 5 }], 'buy', 'sell');
 * // => 10
 */
export declare function sumFieldDifference<T extends GenericObject, P extends NumericDotKey<T>>(data: Maybe<T[]>, first: P, second: P, roundTo?: number): number;
/**
 * * Calculates the total sum of a numeric field across all items.
 *
 * @param data - The array of objects to process.
 * @param field - The field to sum values from. Supports nested dot notation.
 * @param roundTo - Decimal places to round the result to. Defaults to 2.
 * @returns The rounded total sum.
 *
 * @example
 * sumByField([{ a: 5 }, { a: 3 }], 'a');
 * // => 8
 */
export declare function sumByField<T extends GenericObject>(data: Maybe<T[]>, field: NumericDotKey<T>, roundTo?: number): number;
/**
 * * Calculates the average of a numeric field across all items.
 *
 * @param data - The array of objects to process.
 * @param field - The field to calculate the average from. Supports nested dot notation.
 * @param roundTo - Decimal places to round the result to. Defaults to 2.
 * @returns The rounded average.
 *
 * @example
 * averageByField([{ a: 4 }, { a: 6 }], 'a');
 * // => 5
 */
export declare function averageByField<T extends GenericObject>(data: Maybe<T[]>, field: NumericDotKey<T>, roundTo?: number): number;
/**
 * * Groups an array of objects by a primitive field and sums another numeric field per group.
 *
 * @param data - The array of objects to group.
 * @param groupBy - The field to group by. Supports nested dot notation.
 * @param sumBy - The numeric field to sum within each group. Supports nested dot notation.
 * @param roundTo - Decimal places to round each group’s result to. Defaults to 2.
 * @returns An array of records, each with the group key and its corresponding summed value.
 *
 * @example
 * groupAndSumByField([{ type: 'A', val: 2 }, { type: 'A', val: 3 }, { type: 'B', val: 1 }], 'type', 'val');
 * // => [{ A: 5 }, { B: 1 }]
 */
export declare function groupAndSumByField<T extends GenericObject>(data: Maybe<T[]>, groupBy: NestedPrimitiveKey<T>, sumBy: NumericDotKey<T>, roundTo?: number): Array<Record<string, number>>;
/**
 * * Groups an array of objects by a primitive field and averages another numeric field per group.
 *
 * @param data - The array of objects to group.
 * @param groupBy - The field to group by. Supports nested dot notation.
 * @param averageBy - The numeric field to average within each group. Supports nested dot notation.
 * @param roundTo - Decimal places to round each group’s average to. Defaults to 2.
 * @returns An array of records, each with the group key and its corresponding average value.
 *
 * @example
 * groupAndAverageByField([{ type: 'A', val: 2 }, { type: 'A', val: 4 }, { type: 'B', val: 6 }], 'type', 'val');
 * // => [{ A: 3 }, { B: 6 }]
 */
export declare function groupAndAverageByField<T extends GenericObject>(data: Maybe<T[]>, groupBy: NestedPrimitiveKey<T>, averageBy: NumericDotKey<T>, roundTo?: number): Array<Record<string, number>>;