min

Returns the smallest number in an array.

Source Code

View Source Code

import { assert } from '../function/assert';
import { compare } from '../function/compare';
import { IS_ARRAY_ERROR_MSG, isArray } from '../typed/isArray';

/**
 * Finds the minimum item in an array.
 *
 * @description
 * This function can be used to find the minimum number, string, or any other type of item in an array.
 *
 * @example
 * ```ts
 * min([1, 2, 3]); // 1
 * min([{ value: 1 }, { value: 2 }, { value: 3 }], item => item.value); // 1
 * min(['apple', 'banana', 'cherry']); // 'apple'
 * min([new Date('2023-01-01'), new Date('2022-01-01')]); // 2022-01-01
 * ```
 *
 * @param array - The array to be searched.
 * @param [callback] - (optional) The function to invoke for each element in the array to determine its value.
 *
 * @return The item with the minimum value as determined by the callback function.
 *
 * @throws {TypeError} If the provided array is not an array.
 */
export function min<T>(array: T[], callback?: (item: T) => string | number | Date): T | undefined {
  assert(isArray(array), IS_ARRAY_ERROR_MSG, { args: { array }, type: TypeError });

  if (array.length === 0) return undefined;

  const fn = callback ?? ((item: T) => item);
  let current = array[0];

  for (let i = 1; i < array.length; i++) {
    if (compare(fn(array[i]), fn(current)) < 0) {
      current = array[i];
    }
  }

  return current;
}

API

function min(numbers: number[]): number | undefined;

Example

import { min } from '@vielzeug/toolkit';

min([1, 5, 3, 9, 2]); // 1
min([]); // undefined

Notes

• Returns undefined for an empty array.
• Ignores non-numeric values (if any).

Related

• max
• clamp