feat: add deficient number algorithm

Maths/DeficientNumber.js

@@ -0,0 +1,28 @@
+/**
+ * @function isDeficientNumber
+ * @description A deficient number is a positive integer for which the
+ *   sum of its proper divisors is less than the number itself.
+ *   For example, 9 is deficient because 1+3=4 < 9.
+ * @param {number} n - A positive integer
+ * @returns {boolean} - True if n is a deficient number, false otherwise
+ * @see https://en.wikipedia.org/wiki/Deficient_number
+ * @example isDeficientNumber(9) => true
+ * @example isDeficientNumber(10) => false
+ * @example isDeficientNumber(1) => true
+ */
+const isDeficientNumber = (n) => {
+  if (!Number.isInteger(n) || n < 1) {
+    throw new TypeError('Input must be a positive integer')
+  }
+  if (n === 1) return false
+  let sum = 1
+  for (let i = 2; i <= Math.sqrt(n); i++) {
+    if (n % i === 0) {
+      sum += i
+      if (i !== n / i) sum += n / i
+    }
+  }
+  return sum < n
+}
+
+export { isDeficientNumber }

Maths/test/DeficientNumber.test.js

@@ -0,0 +1,49 @@
+import { isDeficientNumber } from '../DeficientNumber.js'
+
+describe('isDeficientNumber', () => {
+  test('1 is NOT a deficient number', () => {
+    expect(isDeficientNumber(1)).toBe(false)
+  })
+
+  test('9 is a deficient number (1+3=4 < 9)', () => {
+    expect(isDeficientNumber(9)).toBe(true)
+  })
+
+  test('10 is a deficient number (1+2+5=8 < 10)', () => {
+    expect(isDeficientNumber(10)).toBe(true)
+  })
+
+  test('prime numbers are deficient', () => {
+    expect(isDeficientNumber(7)).toBe(true)
+    expect(isDeficientNumber(11)).toBe(true)
+    expect(isDeficientNumber(13)).toBe(true)
+  })
+
+  test('6 is NOT deficient (perfect number)', () => {
+    expect(isDeficientNumber(6)).toBe(false)
+  })
+
+  test('12 is NOT deficient (abundant number)', () => {
+    expect(isDeficientNumber(12)).toBe(false)
+  })
+
+  test('28 is NOT deficient (perfect number)', () => {
+    expect(isDeficientNumber(28)).toBe(false)
+  })
+
+  test('18 is NOT deficient (abundant number)', () => {
+    expect(isDeficientNumber(18)).toBe(false)
+  })
+
+  test('throws TypeError for zero', () => {
+    expect(() => isDeficientNumber(0)).toThrow(TypeError)
+  })
+
+  test('throws TypeError for negative input', () => {
+    expect(() => isDeficientNumber(-9)).toThrow(TypeError)
+  })
+
+  test('throws TypeError for float input', () => {
+    expect(() => isDeficientNumber(9.5)).toThrow(TypeError)
+  })
+})