Add binary search algorithm implementation with tests and docs

Author: toramanomer

README.md

@@ -6,3 +6,12 @@ Linear search is a searching algorithm that sequentially checks each element in
 
 -   **Best Case:** **O(1)** (Element found at the beginning)
 -   **Worst Case:** **O(n)** (Element at the end or not present)
+
+# Binary Search
+
+Binary search is a searching algorithm that find the desiired element in a **sorted** sequence by repeatedly dividing the search interval in half until the target is found or the interval is empty.
+
+## Time Complexity
+
+-   **Best Case:** **O(1)** (Element is in the middle)
+-   **Worst Case:** **O(log n)** (Element at the end or not present)

src/algorithms/searching/binarySearch.ts

@@ -0,0 +1,17 @@
+export const binarySearch = <T>(
+	array: T[],
+	target: T
+): { index: number; element: T } | null => {
+	const search = (leftIndex: number, rightIndex: number) => {
+		if (leftIndex > rightIndex) return null
+
+		const midIndex = Math.floor((leftIndex + rightIndex) / 2)
+		const midElement = array[midIndex]
+
+		if (target === midElement)
+			return { index: midIndex, element: midElement }
+		if (target > midElement) return search(midIndex + 1, rightIndex)
+		return search(leftIndex, midIndex - 1)
+	}
+	return search(0, array.length - 1)
+}

tests/algorithms/searching/binarySearch.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from 'vitest'
+import { binarySearch } from '../../../src/algorithms/searching/binarySearch'
+
+describe('binarySearch', () => {
+	describe('when array is empty', () => {
+		it('should return null', () => {
+			expect(binarySearch([], 1)).toBeNull()
+		})
+	})
+
+	describe('when the array has even number of elements', () => {
+		describe('and target is in the list', () => {
+			const vectors = Array.from({ length: 10 }, (_, index) => ({
+				array: Array.from({ length: 10 }, (_, index) => index + 1),
+				target: index + 1,
+				expected: { index, element: index + 1 }
+			}))
+
+			it('should return the target with its index', () => {
+				vectors.forEach(({ array, target, expected }) => {
+					expect(binarySearch(array, target)).toStrictEqual(expected)
+				})
+			})
+		})
+
+		describe('and target is not in the list', () => {
+			const vectors = Array.from({ length: 10 }, (_, index) => ({
+				array: Array.from({ length: 10 }, (_, index) => index + 1),
+				target: 100
+			}))
+
+			it('should return null', () => {
+				vectors.forEach(({ array, target }) => {
+					expect(binarySearch(array, target)).toBeNull()
+				})
+			})
+		})
+	})
+
+	describe('when the array has odd number of elements', () => {
+		describe('and target is in the list', () => {
+			const vectors = Array.from({ length: 11 }, (_, index) => ({
+				array: Array.from({ length: 11 }, (_, index) => index + 1),
+				target: index + 1,
+				expected: { index, element: index + 1 }
+			}))
+
+			it('should return the target with its index', () => {
+				vectors.forEach(({ array, target, expected }) => {
+					expect(binarySearch(array, target)).toStrictEqual(expected)
+				})
+			})
+		})
+
+		describe('and target is not in the list', () => {
+			const vectors = Array.from({ length: 11 }, (_, index) => ({
+				array: Array.from({ length: 11 }, (_, index) => index + 1),
+				target: 100
+			}))
+
+			it('should return null', () => {
+				vectors.forEach(({ array, target }) => {
+					expect(binarySearch(array, target)).toBeNull()
+				})
+			})
+		})
+	})
+})