gaussian-helper

A robust, type-safe library for statistical calculations in TypeScript/JavaScript.

Installation

npm install gaussian-helper
# or
yarn add gaussian-helper

Quick Start

import { getMean, getMedian, getStandardDeviation } from 'gaussian-helper';

const data = [10, 2, 3, 4, 5];

const mean = getMean(data); // 4.8
const median = getMedian(data); // 4
const std = getStandardDeviation([1, 2, 3, 4, 5]); // 1.414... (population)
const sampleStd = getStandardDeviation([1, 2, 3, 4, 5], { sample: true }); // 1.581... (sample)

API Reference

getMean(array: number[]): number

Calculates the arithmetic mean (average) of an array of numbers.

Parameters:

• array - Array of numbers

Returns: The arithmetic mean

Throws:

• Error - If the array is empty
• TypeError - If the array contains NaN or Infinity

Examples:

getMean([1, 2, 3, 4, 5]); // 3
getMean([10, 20, 30]); // 20
getMean([-5, 0, 5]); // 0

getMedian(values: number[]): number

Calculates the median (middle value) of an array of numbers.

For odd-length arrays, returns the middle element. For even-length arrays, returns the average of the two middle elements.

Important: This function does not mutate the original array.

Parameters:

• values - Array of numbers

Returns: The median value

Throws:

• Error - If the array is empty
• TypeError - If the array contains NaN or Infinity

Examples:

getMedian([1, 2, 3, 4, 5]); // 3 (middle value)
getMedian([1, 2, 3, 4]); // 2.5 (average of 2 and 3)
getMedian([5, 1, 3]); // 3 (automatically sorted)

// Original array is NOT modified
const data = [5, 2, 8];
getMedian(data); // 5
console.log(data); // [5, 2, 8] - unchanged

getStandardDeviation(values: number[], options?: StandardDeviationOptions): number

Calculates the standard deviation of an array of numbers.

Standard deviation measures the amount of variation or dispersion in a dataset. A low standard deviation indicates values are close to the mean, while a high standard deviation indicates values are spread out.

Parameters:

• values - Array of numbers
• options - Configuration object (optional)
  • sample (boolean, default: false) - If true, calculates sample standard deviation (n-1). If false, calculates population standard deviation (n).

Returns: The standard deviation

Throws:

• Error - If the array is empty
• Error - If sample: true and array has fewer than 2 values
• TypeError - If the array contains NaN or Infinity

Population vs Sample:

• Population (default, divides by n): Use when your data represents the entire population
• Sample (divides by n-1): Use when your data is a sample from a larger population (Bessel's correction)

Examples:

// Population standard deviation (default)
getStandardDeviation([1, 2, 3, 4, 5]); // ~1.414

// Sample standard deviation (with Bessel's correction)
getStandardDeviation([1, 2, 3, 4, 5], { sample: true }); // ~1.581

// All identical values = zero deviation
getStandardDeviation([5, 5, 5, 5]); // 0

// Large variance
getStandardDeviation([1, 100, 1000]); // ~449.42

Features

• ✅ Immutable operations - Never modifies input arrays
• ✅ Robust validation - Detects and rejects NaN, Infinity, and empty arrays
• ✅ Overflow protection - Safe handling of very large numbers
• ✅ Full TypeScript support - Complete type definitions and JSDoc
• ✅ Zero dependencies - Lightweight and secure
• ✅ 100% test coverage - 37 comprehensive tests
• ✅ Population & Sample modes - Flexible standard deviation calculation

Error Handling

All functions throw descriptive errors for invalid inputs:

// Empty arrays
getMean([]); // Error: Cannot calculate mean of an empty array

// Non-finite numbers
getMean([1, NaN, 3]); // TypeError: Array contains non-finite numbers (NaN or Infinity)
getMean([1, Infinity, 3]); // TypeError: Array contains non-finite numbers (NaN or Infinity)

// Sample std with insufficient data
getStandardDeviation([42], { sample: true });
// Error: Sample standard deviation requires at least 2 values (cannot divide by n-1 when n=1)

TypeScript Support

This library is written in TypeScript and includes full type definitions:

import {
  getMean,
  getMedian,
  getStandardDeviation,
  StandardDeviationOptions
} from 'gaussian-helper';

const data: number[] = [1, 2, 3, 4, 5];
const mean: number = getMean(data);
const options: StandardDeviationOptions = { sample: true };

License

MIT