calcufly-math 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CalcuFly (https://calcufly.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# calcufly-math
+
+Math and statistics calculator functions for Node.js. Percentages, fractions, geometry, algebra, statistics, trigonometry and more.
+
+Part of the [CalcuFly](https://calcufly.com) calculator suite — 600+ free online calculators.
+
+## Installation
+
+```bash
+npm install calcufly-math
+```
+
+## Quick Start
+
+```javascript
+const math = require('calcufly-math');
+
+// Quadratic equation
+const roots = math.quadratic(1, -5, 6);
+console.log(roots); // { x1: 3, x2: 2 }
+
+// Statistics
+const data = [4, 8, 15, 16, 23, 42];
+console.log(math.mean(data));   // 18
+console.log(math.median(data)); // 15.5
+console.log(math.standardDeviation(data));
+
+// Geometry
+console.log(math.circleArea(5));      // 78.54
+console.log(math.sphereVolume(3));    // 113.10
+console.log(math.pythagorean(3, 4));  // 5
+```
+
+## API Reference
+
+| Function | Description |
+|----------|-------------|
+| `percentage(value, percent)` | Percentage of a value |
+| `percentageChange(old, new)` | Percentage change |
+| `gcd(a, b)` | Greatest common divisor |
+| `lcm(a, b)` | Least common multiple |
+| `quadratic(a, b, c)` | Solve quadratic equation |
+| `mean(numbers)` | Average |
+| `median(numbers)` | Median value |
+| `mode(numbers)` | Most frequent values |
+| `standardDeviation(numbers)` | Std deviation |
+| `correlation(x, y)` | Pearson correlation |
+| `factorial(n)` | Factorial |
+| `permutations(n, r)` | Permutations |
+| `combinations(n, r)` | Combinations |
+| `circleArea(r)` | Circle area |
+| `triangleAreaHeron(a, b, c)` | Triangle area (Heron) |
+| `sphereVolume(r)` | Sphere volume |
+| `pythagorean(a, b)` | Hypotenuse |
+| `isPrime(n)` | Prime check |
+| `primeFactors(n)` | Prime factorization |
+| `fibonacci(n)` | Fibonacci sequence |
+
+Try these calculations online at **[CalcuFly.com](https://calcufly.com)** — free, no signup required.
+
+## License
+
+MIT — [CalcuFly](https://calcufly.com)

package/index.js

@@ -0,0 +1,525 @@
+/**
+ * calcufly-math
+ * Math and statistics calculator functions.
+ * Part of the CalcuFly calculator suite — https://calcufly.com
+ */
+
+'use strict';
+
+// ─── PERCENTAGE ───────────────────────────────────────────────────────────────
+
+/**
+ * Calculate a percentage of a value.
+ * @param {number} value - The base value.
+ * @param {number} percent - The percentage to apply.
+ * @returns {number}
+ */
+function percentage(value, percent) {
+  return (value * percent) / 100;
+}
+
+/**
+ * Calculate the percentage change between two values.
+ * @param {number} oldVal
+ * @param {number} newVal
+ * @returns {{ change: number, percentChange: number }}
+ */
+function percentageChange(oldVal, newVal) {
+  const change = newVal - oldVal;
+  const percentChange = (change / Math.abs(oldVal)) * 100;
+  return { change, percentChange };
+}
+
+/**
+ * Calculate what percentage a part is of a whole.
+ * @param {number} part
+ * @param {number} whole
+ * @returns {number}
+ */
+function percentageOf(part, whole) {
+  return (part / whole) * 100;
+}
+
+// ─── FRACTIONS ────────────────────────────────────────────────────────────────
+
+/**
+ * Convert a fraction to a decimal.
+ * @param {number} numerator
+ * @param {number} denominator
+ * @returns {number}
+ */
+function fractionToDecimal(numerator, denominator) {
+  if (denominator === 0) throw new Error('Denominator cannot be zero.');
+  return numerator / denominator;
+}
+
+/**
+ * Convert a decimal to a fraction (approximate).
+ * @param {number} decimal
+ * @param {number} [tolerance=1e-6]
+ * @returns {{ numerator: number, denominator: number }}
+ */
+function decimalToFraction(decimal, tolerance = 1e-6) {
+  if (decimal === 0) return { numerator: 0, denominator: 1 };
+  const sign = decimal < 0 ? -1 : 1;
+  decimal = Math.abs(decimal);
+  let h1 = 1, h2 = 0, k1 = 0, k2 = 1;
+  let b = decimal;
+  do {
+    const a = Math.floor(b);
+    let aux = h1;
+    h1 = a * h1 + h2;
+    h2 = aux;
+    aux = k1;
+    k1 = a * k1 + k2;
+    k2 = aux;
+    b = 1 / (b - a);
+  } while (Math.abs(decimal - h1 / k1) > decimal * tolerance);
+  return { numerator: sign * h1, denominator: k1 };
+}
+
+/**
+ * Simplify a fraction to its lowest terms.
+ * @param {number} numerator
+ * @param {number} denominator
+ * @returns {{ numerator: number, denominator: number }}
+ */
+function simplifyFraction(numerator, denominator) {
+  const d = gcd(Math.abs(numerator), Math.abs(denominator));
+  return { numerator: numerator / d, denominator: denominator / d };
+}
+
+// ─── NUMBER THEORY ────────────────────────────────────────────────────────────
+
+/**
+ * Greatest Common Divisor (Euclidean algorithm).
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ */
+function gcd(a, b) {
+  a = Math.abs(Math.round(a));
+  b = Math.abs(Math.round(b));
+  while (b !== 0) {
+    [a, b] = [b, a % b];
+  }
+  return a;
+}
+
+/**
+ * Least Common Multiple.
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ */
+function lcm(a, b) {
+  return Math.abs(a * b) / gcd(a, b);
+}
+
+/**
+ * Factorial of n.
+ * @param {number} n - Non-negative integer.
+ * @returns {number}
+ */
+function factorial(n) {
+  if (n < 0) throw new Error('Factorial is not defined for negative numbers.');
+  if (!Number.isInteger(n)) throw new Error('Factorial requires an integer.');
+  if (n === 0 || n === 1) return 1;
+  let result = 1;
+  for (let i = 2; i <= n; i++) result *= i;
+  return result;
+}
+
+/**
+ * Check whether n is a prime number.
+ * @param {number} n
+ * @returns {boolean}
+ */
+function isPrime(n) {
+  if (n < 2) return false;
+  if (n === 2) return true;
+  if (n % 2 === 0) return false;
+  for (let i = 3; i <= Math.sqrt(n); i += 2) {
+    if (n % i === 0) return false;
+  }
+  return true;
+}
+
+/**
+ * Get the prime factors of n.
+ * @param {number} n
+ * @returns {number[]}
+ */
+function primeFactors(n) {
+  const factors = [];
+  let d = 2;
+  while (n > 1) {
+    while (n % d === 0) {
+      factors.push(d);
+      n /= d;
+    }
+    d++;
+  }
+  return factors;
+}
+
+/**
+ * Generate the first n Fibonacci numbers.
+ * @param {number} n
+ * @returns {number[]}
+ */
+function fibonacci(n) {
+  if (n <= 0) return [];
+  if (n === 1) return [0];
+  const seq = [0, 1];
+  for (let i = 2; i < n; i++) seq.push(seq[i - 1] + seq[i - 2]);
+  return seq;
+}
+
+// ─── ALGEBRA ──────────────────────────────────────────────────────────────────
+
+/**
+ * Solve a quadratic equation ax² + bx + c = 0.
+ * @param {number} a
+ * @param {number} b
+ * @param {number} c
+ * @returns {{ x1: number|null, x2: number|null, discriminant: number }}
+ */
+function quadratic(a, b, c) {
+  if (a === 0) throw new Error('Coefficient a cannot be zero for a quadratic equation.');
+  const discriminant = b * b - 4 * a * c;
+  if (discriminant < 0) {
+    return { x1: null, x2: null, discriminant };
+  }
+  const sqrtD = Math.sqrt(discriminant);
+  return {
+    x1: (-b + sqrtD) / (2 * a),
+    x2: (-b - sqrtD) / (2 * a),
+    discriminant,
+  };
+}
+
+/**
+ * Natural logarithm, or log to a custom base.
+ * @param {number} value
+ * @param {number} [base=Math.E]
+ * @returns {number}
+ */
+function logarithm(value, base = Math.E) {
+  if (value <= 0) throw new Error('Logarithm is only defined for positive values.');
+  return Math.log(value) / Math.log(base);
+}
+
+// ─── COMBINATORICS ────────────────────────────────────────────────────────────
+
+/**
+ * Number of permutations P(n, r).
+ * @param {number} n
+ * @param {number} r
+ * @returns {number}
+ */
+function permutations(n, r) {
+  if (r > n) return 0;
+  return factorial(n) / factorial(n - r);
+}
+
+/**
+ * Number of combinations C(n, r).
+ * @param {number} n
+ * @param {number} r
+ * @returns {number}
+ */
+function combinations(n, r) {
+  if (r > n) return 0;
+  return factorial(n) / (factorial(r) * factorial(n - r));
+}
+
+// ─── STATISTICS ───────────────────────────────────────────────────────────────
+
+/**
+ * Arithmetic mean of an array of numbers.
+ * @param {number[]} numbers
+ * @returns {number}
+ */
+function mean(numbers) {
+  if (numbers.length === 0) throw new Error('Array must not be empty.');
+  return numbers.reduce((sum, n) => sum + n, 0) / numbers.length;
+}
+
+/**
+ * Median of an array of numbers.
+ * @param {number[]} numbers
+ * @returns {number}
+ */
+function median(numbers) {
+  if (numbers.length === 0) throw new Error('Array must not be empty.');
+  const sorted = [...numbers].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;
+}
+
+/**
+ * Mode(s) of an array of numbers.
+ * @param {number[]} numbers
+ * @returns {number[]}
+ */
+function mode(numbers) {
+  if (numbers.length === 0) throw new Error('Array must not be empty.');
+  const freq = {};
+  numbers.forEach((n) => { freq[n] = (freq[n] || 0) + 1; });
+  const maxFreq = Math.max(...Object.values(freq));
+  return Object.keys(freq)
+    .filter((k) => freq[k] === maxFreq)
+    .map(Number);
+}
+
+/**
+ * Population and sample variance.
+ * @param {number[]} numbers
+ * @returns {{ population: number, sample: number }}
+ */
+function variance(numbers) {
+  if (numbers.length < 2) throw new Error('Array must have at least 2 elements.');
+  const m = mean(numbers);
+  const squaredDiffs = numbers.map((n) => (n - m) ** 2);
+  const sumSq = squaredDiffs.reduce((s, v) => s + v, 0);
+  return {
+    population: sumSq / numbers.length,
+    sample: sumSq / (numbers.length - 1),
+  };
+}
+
+/**
+ * Population and sample standard deviation.
+ * @param {number[]} numbers
+ * @returns {{ population: number, sample: number }}
+ */
+function standardDeviation(numbers) {
+  const v = variance(numbers);
+  return {
+    population: Math.sqrt(v.population),
+    sample: Math.sqrt(v.sample),
+  };
+}
+
+/**
+ * Z-score of a value given mean and standard deviation.
+ * @param {number} value
+ * @param {number} meanVal
+ * @param {number} stdDev
+ * @returns {number}
+ */
+function zScore(value, meanVal, stdDev) {
+  if (stdDev === 0) throw new Error('Standard deviation cannot be zero.');
+  return (value - meanVal) / stdDev;
+}
+
+/**
+ * Pearson correlation coefficient between two arrays.
+ * @param {number[]} xArray
+ * @param {number[]} yArray
+ * @returns {number}
+ */
+function correlation(xArray, yArray) {
+  if (xArray.length !== yArray.length) throw new Error('Arrays must have equal length.');
+  if (xArray.length < 2) throw new Error('Arrays must have at least 2 elements.');
+  const mx = mean(xArray);
+  const my = mean(yArray);
+  const num = xArray.reduce((s, x, i) => s + (x - mx) * (yArray[i] - my), 0);
+  const denX = Math.sqrt(xArray.reduce((s, x) => s + (x - mx) ** 2, 0));
+  const denY = Math.sqrt(yArray.reduce((s, y) => s + (y - my) ** 2, 0));
+  if (denX === 0 || denY === 0) throw new Error('Standard deviation of inputs cannot be zero.');
+  return num / (denX * denY);
+}
+
+// ─── GEOMETRY ─────────────────────────────────────────────────────────────────
+
+/**
+ * Area of a circle.
+ * @param {number} radius
+ * @returns {number}
+ */
+function circleArea(radius) {
+  return Math.PI * radius * radius;
+}
+
+/**
+ * Circumference of a circle.
+ * @param {number} radius
+ * @returns {number}
+ */
+function circleCircumference(radius) {
+  return 2 * Math.PI * radius;
+}
+
+/**
+ * Area of a rectangle.
+ * @param {number} length
+ * @param {number} width
+ * @returns {number}
+ */
+function rectangleArea(length, width) {
+  return length * width;
+}
+
+/**
+ * Area of a triangle (base × height / 2).
+ * @param {number} base
+ * @param {number} height
+ * @returns {number}
+ */
+function triangleArea(base, height) {
+  return (base * height) / 2;
+}
+
+/**
+ * Area of a triangle using Heron's formula.
+ * @param {number} a - Side a.
+ * @param {number} b - Side b.
+ * @param {number} c - Side c.
+ * @returns {number}
+ */
+function triangleAreaHeron(a, b, c) {
+  const s = (a + b + c) / 2;
+  const area = Math.sqrt(s * (s - a) * (s - b) * (s - c));
+  if (isNaN(area)) throw new Error('The given sides do not form a valid triangle.');
+  return area;
+}
+
+/**
+ * Volume of a sphere.
+ * @param {number} radius
+ * @returns {number}
+ */
+function sphereVolume(radius) {
+  return (4 / 3) * Math.PI * radius ** 3;
+}
+
+/**
+ * Volume of a cylinder.
+ * @param {number} radius
+ * @param {number} height
+ * @returns {number}
+ */
+function cylinderVolume(radius, height) {
+  return Math.PI * radius * radius * height;
+}
+
+/**
+ * Volume of a cone.
+ * @param {number} radius
+ * @param {number} height
+ * @returns {number}
+ */
+function coneVolume(radius, height) {
+  return (1 / 3) * Math.PI * radius * radius * height;
+}
+
+/**
+ * Hypotenuse of a right triangle (Pythagorean theorem).
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ */
+function pythagorean(a, b) {
+  return Math.sqrt(a * a + b * b);
+}
+
+// ─── TRIGONOMETRY ─────────────────────────────────────────────────────────────
+
+/**
+ * Convert degrees to radians.
+ * @param {number} degrees
+ * @returns {number}
+ */
+function degreesToRadians(degrees) {
+  return (degrees * Math.PI) / 180;
+}
+
+/**
+ * Convert radians to degrees.
+ * @param {number} radians
+ * @returns {number}
+ */
+function radiansToDegrees(radians) {
+  return (radians * 180) / Math.PI;
+}
+
+/**
+ * Sine of an angle in degrees.
+ * @param {number} degrees
+ * @returns {number}
+ */
+function sinDeg(degrees) {
+  return Math.sin(degreesToRadians(degrees));
+}
+
+/**
+ * Cosine of an angle in degrees.
+ * @param {number} degrees
+ * @returns {number}
+ */
+function cosDeg(degrees) {
+  return Math.cos(degreesToRadians(degrees));
+}
+
+/**
+ * Tangent of an angle in degrees.
+ * @param {number} degrees
+ * @returns {number}
+ */
+function tanDeg(degrees) {
+  return Math.tan(degreesToRadians(degrees));
+}
+
+// ─── EXPORTS ──────────────────────────────────────────────────────────────────
+
+module.exports = {
+  // Percentage
+  percentage,
+  percentageChange,
+  percentageOf,
+  // Fractions
+  fractionToDecimal,
+  decimalToFraction,
+  simplifyFraction,
+  // Number theory
+  gcd,
+  lcm,
+  factorial,
+  isPrime,
+  primeFactors,
+  fibonacci,
+  // Algebra
+  quadratic,
+  logarithm,
+  // Combinatorics
+  permutations,
+  combinations,
+  // Statistics
+  mean,
+  median,
+  mode,
+  variance,
+  standardDeviation,
+  zScore,
+  correlation,
+  // Geometry
+  circleArea,
+  circleCircumference,
+  rectangleArea,
+  triangleArea,
+  triangleAreaHeron,
+  sphereVolume,
+  cylinderVolume,
+  coneVolume,
+  pythagorean,
+  // Trigonometry
+  degreesToRadians,
+  radiansToDegrees,
+  sinDeg,
+  cosDeg,
+  tanDeg,
+};

package/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "calcufly-math",
+  "version": "1.0.0",
+  "description": "Math and statistics calculator functions - percentages, fractions, geometry, algebra, statistics, trigonometry. By CalcuFly.com",
+  "main": "index.js",
+  "keywords": ["math", "calculator", "statistics", "geometry", "algebra", "percentage", "fraction", "trigonometry", "area", "volume", "mean", "median", "standard-deviation", "quadratic", "gcd", "lcm"],
+  "author": "CalcuFly <contact@calcufly.com>",
+  "license": "MIT",
+  "homepage": "https://calcufly.com",
+  "repository": { "type": "git", "url": "https://github.com/mansouewalks-bit2/calcufly-math" },
+  "bugs": { "url": "https://github.com/mansouewalks-bit2/calcufly-math/issues" }
+}