feat: add mean() to stats module in @observerly/fits

src/stats/__tests__/mean.spec.ts

@@ -0,0 +1,65 @@
+/*****************************************************************************************************************/
+
+// @author         Michael Roberts <[email protected]>
+// @package        @observerly/fits
+// @license        Copyright © 2021-2025 observerly
+
+/*****************************************************************************************************************/
+
+import { describe, expect, it } from 'vitest'
+
+import { mean } from '../mean'
+
+/*****************************************************************************************************************/
+
+describe('mean', () => {
+  it('should calculate the mean of an array with positive numbers', () => {
+    const input = [1, 2, 3, 4, 5]
+    const result = mean(input)
+    expect(result).toBe(3) // (1 + 2 + 3 + 4 + 5) / 5 = 3
+  })
+
+  it('should calculate the mean of an array with negative numbers', () => {
+    const input = [-1, -2, -3, -4, -5]
+    const result = mean(input)
+    expect(result).toBe(-3) // (-1 + -2 + -3 + -4 + -5) / 5 = -3
+  })
+
+  it('should calculate the mean of an array with mixed positive and negative numbers', () => {
+    const input = [-3, -2, -1, 1, 2, 3]
+    const result = mean(input)
+    expect(result).toBe(0) // (-3 + -2 + -1 + 1 + 2 + 3) / 6 = 0
+  })
+
+  it('should calculate the mean of an array with a single element', () => {
+    const input = [42]
+    const result = mean(input)
+    expect(result).toBe(42) // Mean of a single element is the element itself
+  })
+
+  it('should handle an empty array gracefully', () => {
+    const input: number[] = []
+    expect(mean(input)).toBeNaN()
+  })
+
+  it('should calculate the mean of an array with floating-point numbers', () => {
+    const input = [1.5, 2.5, 3.5, 4.5]
+    const result = mean(input)
+    expect(result).toBe(3) // (1.5 + 2.5 + 3.5 + 4.5) / 4 = 3
+  })
+
+  it('should handle arrays with repeated values', () => {
+    const input = [2, 2, 2, 2]
+    const result = mean(input)
+    expect(result).toBe(2) // Mean of identical values is the value itself
+  })
+
+  it('should not mutate the original array', () => {
+    const input = [1, 2, 3, 4]
+    const original = [...input]
+    mean(input)
+    expect(input).toEqual(original)
+  })
+})
+
+/*****************************************************************************************************************/

src/stats/index.ts

@@ -6,6 +6,7 @@
 
 /*****************************************************************************************************************/
 
+export { mean } from './mean'
 export { median } from './median'
 
 /*****************************************************************************************************************/

src/stats/mean.ts

@@ -0,0 +1,13 @@
+/*****************************************************************************************************************/
+
+// @author         Michael Roberts <[email protected]>
+// @package        @observerly/fits
+// @license        Copyright © 2021-2025 observerly
+
+/*****************************************************************************************************************/
+
+export const mean = (arr: number[]): number => {
+  return arr.reduce((a, b) => a + b, 0) / arr.length
+}
+
+/*****************************************************************************************************************/