median

Returns the median value of an array of numbers.

Implementation

View Source Code

/**
 * Returns the median of an array of numbers.
 *
 * @example
 * ```ts
 * median([1, 2, 3, 4, 100]); // 3
 * median([1, 2, 3, 4, 5], (n) => n * 2); // 6
 * median([]); // undefined
 * median([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]); // 5.5
 * median([new Date(2020-01-01), new Date(2020-01-02), new Date(2020-01-31)]) // 2020-01-02
 * ```
 *
 * @param arr - The array of numbers.
 * @param callback - (optional) A callback function to map the numbers.
 * @returns The median of the numbers.
 */
export function median<T>(arr: T[], callback?: (item: T) => number | Date): number | Date | undefined {
  if (arr.length === 0) return undefined;

  const values = callback ? arr.map(callback) : (arr as unknown as (number | Date)[]);
  const allDates = values.every((v) => v instanceof Date);
  const numericValues = values.map((v) => (v instanceof Date ? v.getTime() : (v as number)));

  numericValues.sort((a, b) => a - b);

  const mid = Math.floor(numericValues.length / 2);
  const medianValue =
    numericValues.length % 2 === 0 ? (numericValues[mid - 1] + numericValues[mid]) / 2 : numericValues[mid];

  return (allDates ? new Date(medianValue) : medianValue) as unknown as number | Date;
}

API

function median<T>(arr: T[], callback?: (item: T) => number | Date): number | Date | undefined;

Example

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

median([1, 2, 3, 4, 5]); // 3
median([1, 2, 3, 4]); // 2.5
median([]); // undefined

// With callback
const items = [{ score: 85 }, { score: 90 }, { score: 95 }];
median(items, (item) => item.score); // 90

// With Dates
const dates = [new Date('2024-01-01'), new Date('2024-01-05'), new Date('2024-01-10')];
median(dates); // Date object representing 2024-01-05

Notes

• Returns undefined for an empty array.
• The array is not mutated.

Related

• average
• sum