From a29faa17ca14cfab167262b145568c7ac1c7fd14 Mon Sep 17 00:00:00 2001
From: sarthakgupta1907-cell <sarthakgupta1907@gmail.com>
Date: Tue, 3 Nov 2026 22:26:45 +0530
Subject: [PATCH] feat: add find median algorithm

---
 Maths/FindMedian.js           | 28 ++++++++++++++++++++
 Maths/test/FindMedian.test.js | 49 +++++++++++++++++++++++++++++++++++
 2 files changed, 77 insertions(+)
 create mode 100644 Maths/FindMedian.js
 create mode 100644 Maths/test/FindMedian.test.js

diff --git a/Maths/FindMedian.js b/Maths/FindMedian.js
new file mode 100644
index 0000000000..30f13db1df
--- /dev/null
+++ b/Maths/FindMedian.js
@@ -0,0 +1,28 @@
+/**
+ * @function findMedian
+ * @description Finds the median value of an array of numbers.
+ *   The median is the middle value when the array is sorted.
+ *   If the array has an even number of elements, the median is
+ *   the average of the two middle values.
+ * @param {number[]} arr - An array of numbers
+ * @returns {number} - The median value
+ * @see https://en.wikipedia.org/wiki/Median
+ * @example findMedian([1, 2, 3]) => 2
+ * @example findMedian([1, 2, 3, 4]) => 2.5
+ * @example findMedian([5, 3, 1, 4, 2]) => 3
+ */
+const findMedian = (arr) => {
+  if (!Array.isArray(arr) || arr.length === 0) {
+    throw new TypeError('Input must be a non-empty array')
+  }
+  if (!arr.every((n) => typeof n === 'number' && !isNaN(n))) {
+    throw new TypeError('All elements must be numbers')
+  }
+  const sorted = [...arr].sort((a, b) => a - b)
+  const mid = Math.floor(sorted.length / 2)
+  return sorted.length % 2 !== 0
+    ? sorted[mid]
+    : (sorted[mid - 1] + sorted[mid]) / 2
+}
+
+export { findMedian }
diff --git a/Maths/test/FindMedian.test.js b/Maths/test/FindMedian.test.js
new file mode 100644
index 0000000000..be0dafe3cf
--- /dev/null
+++ b/Maths/test/FindMedian.test.js
@@ -0,0 +1,49 @@
+import { findMedian } from '../FindMedian.js'
+
+describe('findMedian', () => {
+  test('findMedian([1, 2, 3]) returns 2', () => {
+    expect(findMedian([1, 2, 3])).toBe(2)
+  })
+
+  test('findMedian([1, 2, 3, 4]) returns 2.5', () => {
+    expect(findMedian([1, 2, 3, 4])).toBe(2.5)
+  })
+
+  test('findMedian([5, 3, 1, 4, 2]) returns 3', () => {
+    expect(findMedian([5, 3, 1, 4, 2])).toBe(3)
+  })
+
+  test('findMedian single element returns that element', () => {
+    expect(findMedian([42])).toBe(42)
+  })
+
+  test('findMedian([1, 1, 1]) returns 1', () => {
+    expect(findMedian([1, 1, 1])).toBe(1)
+  })
+
+  test('findMedian works with negative numbers', () => {
+    expect(findMedian([-3, -1, -2])).toBe(-2)
+  })
+
+  test('findMedian works with decimals', () => {
+    expect(findMedian([1.5, 2.5, 3.5])).toBe(2.5)
+  })
+
+  test('findMedian does not mutate original array', () => {
+    const arr = [3, 1, 2]
+    findMedian(arr)
+    expect(arr).toEqual([3, 1, 2])
+  })
+
+  test('throws TypeError for empty array', () => {
+    expect(() => findMedian([])).toThrow(TypeError)
+  })
+
+  test('throws TypeError for non-array input', () => {
+    expect(() => findMedian('123')).toThrow(TypeError)
+  })
+
+  test('throws TypeError for array with non-numbers', () => {
+    expect(() => findMedian([1, 'two', 3])).toThrow(TypeError)
+  })
+})