@fluixi/utils 1.0.0-alpha.100

package/dist/lib/maths/fn/advanced.js

@@ -0,0 +1,264 @@
+/**
+ * Advanced mathematical operations.
+ * @module AdvancedMathFunctions
+ */
+import { gcd, round } from './basic.js';
+/**
+ * Calculates the natural logarithm of a number.
+ * @param value - The number
+ * @returns The natural logarithm
+ * @throws {Error} If value is not positive
+ */
+export function ln(value) {
+    if (value <= 0) {
+        throw new Error('Natural logarithm is only defined for positive numbers');
+    }
+    return Math.log(value);
+}
+/**
+ * Calculates the base-10 logarithm of a number.
+ * @param value - The number
+ * @returns The base-10 logarithm
+ * @throws {Error} If value is not positive
+ */
+export function log10(value) {
+    if (value <= 0) {
+        throw new Error('Logarithm is only defined for positive numbers');
+    }
+    return Math.log10(value);
+}
+/**
+ * Calculates the base-2 logarithm of a number.
+ * @param value - The number
+ * @returns The base-2 logarithm
+ * @throws {Error} If value is not positive
+ */
+export function log2(value) {
+    if (value <= 0) {
+        throw new Error('Logarithm is only defined for positive numbers');
+    }
+    return Math.log2(value);
+}
+/**
+ * Calculates the logarithm of a number with a custom base.
+ * @param value - The number
+ * @param base - The logarithm base
+ * @returns The logarithm with specified base
+ * @throws {Error} If value or base is not positive
+ */
+export function log(value, base) {
+    if (value <= 0 || base <= 0) {
+        throw new Error('Logarithm is only defined for positive numbers and bases');
+    }
+    return Math.log(value) / Math.log(base);
+}
+/**
+ * Calculates the exponential function e^x.
+ * @param x - The exponent
+ * @returns e raised to the power x
+ */
+export function exp(x) {
+    return Math.exp(x);
+}
+/**
+ * Calculates the cube root of a number.
+ * @param value - The number
+ * @returns The cube root
+ */
+export function cbrt(value) {
+    return Math.cbrt(value);
+}
+/**
+ * Calculates the nth root of a number.
+ * @param value - The number
+ * @param n - The root degree
+ * @returns The nth root
+ * @throws {Error} If n is 0 or value is negative for even n
+ */
+export function nthRoot(value, n) {
+    if (n === 0) {
+        throw new Error('Cannot calculate 0th root');
+    }
+    if (value < 0 && n % 2 === 0) {
+        throw new Error('Cannot calculate even root of negative number');
+    }
+    const exponent = 1 / n;
+    return Math.sign(value) * Math.pow(Math.abs(value), exponent);
+}
+/**
+ * Solves a quadratic equation ax^2 + bx + c = 0.
+ * @param a - Coefficient of x^2
+ * @param b - Coefficient of x
+ * @param c - Constant term
+ * @returns Array of real roots (0, 1, or 2 roots)
+ */
+export function solveQuadratic(a, b, c) {
+    if (a === 0) {
+        // Linear equation
+        if (b === 0)
+            return [];
+        return [-c / b];
+    }
+    const discriminant = b * b - 4 * a * c;
+    if (discriminant < 0) {
+        return [];
+    }
+    else if (discriminant === 0) {
+        return [-b / (2 * a)];
+    }
+    else {
+        const sqrtDiscriminant = Math.sqrt(discriminant);
+        return [
+            (-b - sqrtDiscriminant) / (2 * a),
+            (-b + sqrtDiscriminant) / (2 * a)
+        ];
+    }
+}
+/**
+ * Evaluates a polynomial at a given x value.
+ * @param coefficients - Polynomial coefficients from highest to lowest degree
+ * @param x - The value to evaluate at
+ * @returns The polynomial value at x
+ */
+export function evaluatePolynomial(coefficients, x) {
+    let result = 0;
+    for (let i = 0; i < coefficients.length; i++) {
+        result = result * x + coefficients[i];
+    }
+    return result;
+}
+/**
+ * Simplifies a fraction to its lowest terms.
+ * @param fraction - The fraction to simplify
+ * @returns The simplified fraction
+ */
+export function simplifyFraction(fraction) {
+    const divisor = gcd(fraction.numerator, fraction.denominator);
+    return {
+        numerator: fraction.numerator / divisor,
+        denominator: fraction.denominator / divisor
+    };
+}
+/**
+ * Adds two fractions.
+ * @param a - First fraction
+ * @param b - Second fraction
+ * @returns The sum as a simplified fraction
+ */
+export function addFractions(a, b) {
+    const numerator = a.numerator * b.denominator + b.numerator * a.denominator;
+    const denominator = a.denominator * b.denominator;
+    return simplifyFraction({ numerator, denominator });
+}
+/**
+ * Multiplies two fractions.
+ * @param a - First fraction
+ * @param b - Second fraction
+ * @returns The product as a simplified fraction
+ */
+export function multiplyFractions(a, b) {
+    const numerator = a.numerator * b.numerator;
+    const denominator = a.denominator * b.denominator;
+    return simplifyFraction({ numerator, denominator });
+}
+/**
+ * Calculates the percentage of a number.
+ * @param value - The number
+ * @param percentage - The percentage (e.g., 25 for 25%)
+ * @param precision - The number of decimal places
+ * @returns The percentage of the number
+ */
+export const percentage = (value, total, precision = 2) => {
+    if (total === 0)
+        return 0;
+    const percent = (value / total) * 100;
+    return round(percent, precision);
+};
+/**
+ * Converts a number to a specified base (2-36)
+ *
+ * @param number - The number
+ */
+export const toBase = (number, base, minLength = 1) => {
+    if (base < 2 || base > 36) {
+        throw new Error('Base must be between 2 and 36');
+    }
+    const result = number.toString(base);
+    return result.padStart(minLength, '0');
+};
+/**
+ * Converts a number to ordinal string (1st, 2nd, 3rd, etc.)
+ *
+ * @param n - The number
+ */
+export const toOrdinal = (n) => {
+    const suffix = ['th', 'st', 'nd', 'rd'];
+    const v = n % 100;
+    return n + (suffix[(v - 20) % 10] || suffix[v] || suffix[0]);
+};
+/**
+ * Generates a sequence of numbers
+ *
+ * @param start - The starting number
+ * @param end - The ending number
+ * @param step - The step size
+ *
+ * @returns An array of numbers
+ */
+export const range = (start, end, step = 1) => {
+    const result = [];
+    if (step === 0)
+        return result;
+    if (step > 0) {
+        for (let i = start; i < end; i += step) {
+            result.push(i);
+        }
+    }
+    else {
+        for (let i = start; i > end; i += step) {
+            result.push(i);
+        }
+    }
+    return result;
+};
+/**
+ * Limits the number of decimal places without rounding
+ *
+ * @param value - The number
+ * @param decimalPlaces - The number of decimal places
+ *
+ * @returns The truncated number
+ */
+export const truncateDecimals = (value, decimalPlaces) => {
+    if (!Number.isFinite(value))
+        return value;
+    const factor = 10 ** decimalPlaces;
+    return Math.trunc(value * factor) / factor;
+};
+/**
+ * Normalizes a value to a 0-1 range based on min/max
+ *
+ * @param value - The number
+ * @param min - The minimum value
+ * @param max - The maximum value
+ *
+ * @returns The normalized value
+ */
+export const normalize = (value, min, max) => {
+    if (min === max)
+        return 0;
+    return (value - min) / (max - min);
+};
+/**
+ * Wraps a value within a range (like modulo for floats)
+ *
+ * @param value - The number
+ * @param min - The minimum value
+ * @param max - The maximum value
+ *
+ * @returns The wrapped value
+ */
+export const wrap = (value, min, max) => {
+    const range = max - min;
+    return ((((value - min) % range) + range) % range) + min;
+};

package/dist/lib/maths/fn/advanced.mjs

@@ -0,0 +1,208 @@
+// src/lib/maths/fn/basic.ts
+var round = (value, precision = 0, mode = "round") => {
+  if (mode === "david") return roundUsingDavidGay(value, precision, mode);
+  if (!Number.isFinite(value)) return value;
+  if (precision === 0) return Math[mode](value);
+  if (precision < 0) {
+    const factor2 = 10 ** -precision;
+    return Math[mode](value / factor2) * factor2;
+  }
+  const factor = 10 ** precision;
+  const epsilon = Math.pow(2, -52);
+  const adjusted = value * factor;
+  const correction = Math.sign(adjusted) * epsilon * Math.abs(adjusted);
+  let rounded;
+  switch (mode) {
+    case "round":
+      rounded = Math.round(adjusted + correction);
+      break;
+    case "ceil":
+      rounded = Math.ceil(adjusted - epsilon);
+      break;
+    case "floor":
+      rounded = Math.floor(adjusted + epsilon);
+      break;
+    case "trunc":
+      rounded = adjusted < 0 ? Math.ceil(adjusted) : Math.floor(adjusted);
+      break;
+    default:
+      rounded = Math.round(adjusted + correction);
+  }
+  return rounded / factor;
+};
+var roundUsingDavidGay = (_value, precision = 0, mode = "round") => {
+  let value = Math.abs(_value);
+  const multiplicator = _value < 0 ? -1 : 1;
+  if (precision === 0) {
+    return Math.round(value) * multiplicator;
+  }
+  if (!Number.isFinite(value)) {
+    return value * multiplicator;
+  }
+  const factor = 10 ** precision;
+  let shifted = value * factor;
+  const epsilon = Math.pow(2, -53);
+  const correction = Math.sign(shifted) * epsilon * Math.abs(shifted);
+  shifted += correction;
+  const rounded = Math.round(shifted);
+  return rounded / factor * multiplicator;
+};
+function gcd(a, b) {
+  a = Math.abs(a);
+  b = Math.abs(b);
+  while (b !== 0) {
+    const temp = b;
+    b = a % b;
+    a = temp;
+  }
+  return a;
+}
+
+// src/lib/maths/fn/advanced.ts
+function ln(value) {
+  if (value <= 0) {
+    throw new Error("Natural logarithm is only defined for positive numbers");
+  }
+  return Math.log(value);
+}
+function log10(value) {
+  if (value <= 0) {
+    throw new Error("Logarithm is only defined for positive numbers");
+  }
+  return Math.log10(value);
+}
+function log2(value) {
+  if (value <= 0) {
+    throw new Error("Logarithm is only defined for positive numbers");
+  }
+  return Math.log2(value);
+}
+function log(value, base) {
+  if (value <= 0 || base <= 0) {
+    throw new Error("Logarithm is only defined for positive numbers and bases");
+  }
+  return Math.log(value) / Math.log(base);
+}
+function exp(x) {
+  return Math.exp(x);
+}
+function cbrt(value) {
+  return Math.cbrt(value);
+}
+function nthRoot(value, n) {
+  if (n === 0) {
+    throw new Error("Cannot calculate 0th root");
+  }
+  if (value < 0 && n % 2 === 0) {
+    throw new Error("Cannot calculate even root of negative number");
+  }
+  const exponent = 1 / n;
+  return Math.sign(value) * Math.pow(Math.abs(value), exponent);
+}
+function solveQuadratic(a, b, c) {
+  if (a === 0) {
+    if (b === 0) return [];
+    return [-c / b];
+  }
+  const discriminant = b * b - 4 * a * c;
+  if (discriminant < 0) {
+    return [];
+  } else if (discriminant === 0) {
+    return [-b / (2 * a)];
+  } else {
+    const sqrtDiscriminant = Math.sqrt(discriminant);
+    return [
+      (-b - sqrtDiscriminant) / (2 * a),
+      (-b + sqrtDiscriminant) / (2 * a)
+    ];
+  }
+}
+function evaluatePolynomial(coefficients, x) {
+  let result = 0;
+  for (let i = 0; i < coefficients.length; i++) {
+    result = result * x + coefficients[i];
+  }
+  return result;
+}
+function simplifyFraction(fraction) {
+  const divisor = gcd(fraction.numerator, fraction.denominator);
+  return {
+    numerator: fraction.numerator / divisor,
+    denominator: fraction.denominator / divisor
+  };
+}
+function addFractions(a, b) {
+  const numerator = a.numerator * b.denominator + b.numerator * a.denominator;
+  const denominator = a.denominator * b.denominator;
+  return simplifyFraction({ numerator, denominator });
+}
+function multiplyFractions(a, b) {
+  const numerator = a.numerator * b.numerator;
+  const denominator = a.denominator * b.denominator;
+  return simplifyFraction({ numerator, denominator });
+}
+var percentage = (value, total, precision = 2) => {
+  if (total === 0) return 0;
+  const percent = value / total * 100;
+  return round(percent, precision);
+};
+var toBase = (number, base, minLength = 1) => {
+  if (base < 2 || base > 36) {
+    throw new Error("Base must be between 2 and 36");
+  }
+  const result = number.toString(base);
+  return result.padStart(minLength, "0");
+};
+var toOrdinal = (n) => {
+  const suffix = ["th", "st", "nd", "rd"];
+  const v = n % 100;
+  return n + (suffix[(v - 20) % 10] || suffix[v] || suffix[0]);
+};
+var range = (start, end, step = 1) => {
+  const result = [];
+  if (step === 0) return result;
+  if (step > 0) {
+    for (let i = start; i < end; i += step) {
+      result.push(i);
+    }
+  } else {
+    for (let i = start; i > end; i += step) {
+      result.push(i);
+    }
+  }
+  return result;
+};
+var truncateDecimals = (value, decimalPlaces) => {
+  if (!Number.isFinite(value)) return value;
+  const factor = 10 ** decimalPlaces;
+  return Math.trunc(value * factor) / factor;
+};
+var normalize = (value, min, max) => {
+  if (min === max) return 0;
+  return (value - min) / (max - min);
+};
+var wrap = (value, min, max) => {
+  const range2 = max - min;
+  return ((value - min) % range2 + range2) % range2 + min;
+};
+export {
+  addFractions,
+  cbrt,
+  evaluatePolynomial,
+  exp,
+  ln,
+  log,
+  log10,
+  log2,
+  multiplyFractions,
+  normalize,
+  nthRoot,
+  percentage,
+  range,
+  simplifyFraction,
+  solveQuadratic,
+  toBase,
+  toOrdinal,
+  truncateDecimals,
+  wrap
+};

package/dist/lib/maths/fn/basic.cjs

@@ -0,0 +1,212 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/lib/maths/fn/basic.ts
+var basic_exports = {};
+__export(basic_exports, {
+  abs: () => abs,
+  add: () => add,
+  average: () => average,
+  ceil: () => ceil,
+  clamp: () => clamp,
+  divide: () => divide,
+  factorial: () => factorial,
+  floor: () => floor,
+  gcd: () => gcd,
+  invLerp: () => invLerp,
+  lcm: () => lcm,
+  lerp: () => lerp,
+  mapRange: () => mapRange,
+  max: () => max,
+  median: () => median,
+  min: () => min,
+  modulo: () => modulo,
+  power: () => power,
+  product: () => product,
+  round: () => round,
+  sign: () => sign,
+  sqrt: () => sqrt,
+  subtract: () => subtract,
+  sum: () => sum,
+  trunc: () => trunc
+});
+module.exports = __toCommonJS(basic_exports);
+function add(a, b) {
+  return a + b;
+}
+function subtract(a, b) {
+  return a - b;
+}
+var divide = (dividend, divisor, fallback) => {
+  if (divisor === 0) {
+    return fallback !== void 0 ? fallback : NaN;
+  }
+  return dividend / divisor;
+};
+function modulo(a, b) {
+  return a % b;
+}
+function power(base, exponent) {
+  return Math.pow(base, exponent);
+}
+function sqrt(value) {
+  if (value < 0) {
+    throw new Error("Cannot calculate square root of negative number");
+  }
+  return Math.sqrt(value);
+}
+function abs(value) {
+  return Math.abs(value);
+}
+var round = (value, precision = 0, mode = "round") => {
+  if (mode === "david") return roundUsingDavidGay(value, precision, mode);
+  if (!Number.isFinite(value)) return value;
+  if (precision === 0) return Math[mode](value);
+  if (precision < 0) {
+    const factor2 = 10 ** -precision;
+    return Math[mode](value / factor2) * factor2;
+  }
+  const factor = 10 ** precision;
+  const epsilon = Math.pow(2, -52);
+  const adjusted = value * factor;
+  const correction = Math.sign(adjusted) * epsilon * Math.abs(adjusted);
+  let rounded;
+  switch (mode) {
+    case "round":
+      rounded = Math.round(adjusted + correction);
+      break;
+    case "ceil":
+      rounded = Math.ceil(adjusted - epsilon);
+      break;
+    case "floor":
+      rounded = Math.floor(adjusted + epsilon);
+      break;
+    case "trunc":
+      rounded = adjusted < 0 ? Math.ceil(adjusted) : Math.floor(adjusted);
+      break;
+    default:
+      rounded = Math.round(adjusted + correction);
+  }
+  return rounded / factor;
+};
+var roundUsingDavidGay = (_value, precision = 0, mode = "round") => {
+  let value = Math.abs(_value);
+  const multiplicator = _value < 0 ? -1 : 1;
+  if (precision === 0) {
+    return Math.round(value) * multiplicator;
+  }
+  if (!Number.isFinite(value)) {
+    return value * multiplicator;
+  }
+  const factor = 10 ** precision;
+  let shifted = value * factor;
+  const epsilon = Math.pow(2, -53);
+  const correction = Math.sign(shifted) * epsilon * Math.abs(shifted);
+  shifted += correction;
+  const rounded = Math.round(shifted);
+  return rounded / factor * multiplicator;
+};
+var ceil = (value, precision = 0) => {
+  return round(value, precision, "ceil");
+};
+var floor = (value, precision = 0) => {
+  return round(value, precision, "floor");
+};
+var trunc = (value, precision = 0) => {
+  return round(value, precision, "trunc");
+};
+var clamp = (value, min2, max2) => {
+  if (min2 > max2) [min2, max2] = [max2, min2];
+  return value < min2 ? min2 : value > max2 ? max2 : value;
+};
+function sign(value) {
+  if (value > 0) return 1;
+  if (value < 0) return -1;
+  return 0;
+}
+function factorial(n) {
+  if (!Number.isInteger(n) || n < 0) {
+    throw new Error("Factorial is only defined for non-negative integers");
+  }
+  if (n === 0 || n === 1) return 1;
+  let result = 1;
+  for (let i = 2; i <= n; i++) {
+    result *= i;
+  }
+  return result;
+}
+function gcd(a, b) {
+  a = Math.abs(a);
+  b = Math.abs(b);
+  while (b !== 0) {
+    const temp = b;
+    b = a % b;
+    a = temp;
+  }
+  return a;
+}
+function lcm(a, b) {
+  return Math.abs(a * b) / gcd(a, b);
+}
+function lerp(start, end, t) {
+  return start + (end - start) * clamp(t, 0, 1);
+}
+var invLerp = (start, end, value) => {
+  return clamp((value - start) / (end - start), 0, 1);
+};
+var mapRange = (value, inMin, inMax, outMin, outMax) => {
+  const t = invLerp(inMin, inMax, value);
+  return lerp(outMin, outMax, t);
+};
+function min(...values) {
+  return Math.min(...values);
+}
+function max(...values) {
+  return Math.max(...values);
+}
+var average = (...numbers) => {
+  if (!Array.isArray(numbers) || numbers.length === 0) return 0;
+  let total = 0;
+  let count = 0;
+  for (const num of numbers) {
+    if (Number.isFinite(num)) {
+      total += num;
+      count++;
+    }
+  }
+  return count === 0 ? 0 : total / count;
+};
+var sum = (...numbers) => {
+  if (!Array.isArray(numbers)) return 0;
+  return numbers.reduce(
+    (acc, val) => acc + (Number.isFinite(val) ? val : 0),
+    0
+  );
+};
+var median = (...numbers) => {
+  if (!Array.isArray(numbers) || numbers.length === 0) return 0;
+  const validNumbers = numbers.filter(Number.isFinite);
+  if (validNumbers.length === 0) return 0;
+  validNumbers.sort((a, b) => a - b);
+  const mid = Math.floor(validNumbers.length / 2);
+  return validNumbers.length % 2 === 0 ? (validNumbers[mid - 1] + validNumbers[mid]) / 2 : validNumbers[mid];
+};
+function product(...values) {
+  return values.reduce((prod, val) => prod * val, 1);
+}