speexjs-core 0.7.0

package/dist/math/index.d.ts

@@ -0,0 +1,362 @@
+/**
+ * Error thrown when attempting to divide by zero.
+ */
+declare class DivisionByZeroError extends Error {
+    constructor();
+}
+/**
+ * Safely adds two numbers, handling floating-point precision.
+ *
+ * @param a - First number.
+ * @param b - Second number.
+ * @returns The sum.
+ */
+declare function add(a: number, b: number): number;
+/**
+ * Safely subtracts two numbers, handling floating-point precision.
+ *
+ * @param a - First number.
+ * @param b - Second number.
+ * @returns The difference.
+ */
+declare function sub(a: number, b: number): number;
+/**
+ * Safely multiplies two numbers, handling floating-point precision.
+ *
+ * @param a - First number.
+ * @param b - Second number.
+ * @returns The product.
+ */
+declare function mul(a: number, b: number): number;
+/**
+ * Safely divides two numbers.
+ *
+ * @param a - The dividend.
+ * @param b - The divisor.
+ * @returns The quotient.
+ * @throws {DivisionByZeroError} If `b` is zero.
+ */
+declare function div(a: number, b: number): number;
+/**
+ * Rounds a number to the given precision.
+ *
+ * @param value - The number to round.
+ * @param precision - Number of decimal places (default 0).
+ * @returns The rounded value.
+ */
+declare function round(value: number, precision?: number): number;
+/**
+ * Floors a number to the given precision.
+ *
+ * @param value - The number to floor.
+ * @param precision - Number of decimal places (default 0).
+ * @returns The floored value.
+ */
+declare function floor(value: number, precision?: number): number;
+/**
+ * Ceils a number to the given precision.
+ *
+ * @param value - The number to ceil.
+ * @param precision - Number of decimal places (default 0).
+ * @returns The ceiled value.
+ */
+declare function ceil(value: number, precision?: number): number;
+/**
+ * Checks if two numbers are approximately equal within a tolerance.
+ *
+ * @param a - First number.
+ * @param b - Second number.
+ * @param tolerance - Maximum difference (default `Number.EPSILON`).
+ * @returns Whether the numbers are approximately equal.
+ */
+declare function approxEqual(a: number, b: number, tolerance?: number): boolean;
+/**
+ * Clamps a value within the inclusive range [min, max].
+ *
+ * @param value - The value to clamp.
+ * @param min - The lower bound.
+ * @param max - The upper bound.
+ * @returns The clamped value.
+ * @throws {RangeError} If `min` exceeds `max`.
+ */
+declare function clamp(value: number, min: number, max: number): number;
+/**
+ * Computes the sum of an array of numbers.
+ *
+ * @param values - Array of numbers.
+ * @returns The total sum.
+ */
+declare function sum(values: number[]): number;
+/**
+ * Computes the average (mean) of an array of numbers.
+ *
+ * @param values - Array of numbers.
+ * @returns The average.
+ * @throws {RangeError} If the array is empty.
+ */
+declare function average(values: number[]): number;
+/**
+ * Generates a random integer between `min` and `max` (inclusive).
+ *
+ * @param min - The minimum integer.
+ * @param max - The maximum integer.
+ * @returns A random integer.
+ * @throws {RangeError} If arguments are not integers or `min > max`.
+ */
+declare function randomInt(min: number, max: number): number;
+/**
+ * Checks if a number is within the inclusive range [min, max].
+ *
+ * @param value - The number to check.
+ * @param min - The lower bound.
+ * @param max - The upper bound.
+ * @returns Whether the value is in range.
+ */
+declare function inRange(value: number, min: number, max: number): boolean;
+/**
+ * Computes the median of an array of numbers.
+ *
+ * @param values - Array of numbers.
+ * @returns The median value.
+ * @throws {RangeError} If the array is empty.
+ */
+declare function median(values: number[]): number;
+/**
+ * Computes the population standard deviation.
+ *
+ * @param values - Array of numbers.
+ * @returns The standard deviation.
+ * @throws {RangeError} If the array has fewer than 2 values.
+ */
+declare function stddev(values: number[]): number;
+/**
+ * Computes the sample standard deviation (Bessel's correction).
+ *
+ * @param values - Array of numbers.
+ * @returns The sample standard deviation.
+ * @throws {RangeError} If the array has fewer than 2 values.
+ */
+declare function sampleStddev(values: number[]): number;
+/**
+ * Computes the percentile value (0-100) using linear interpolation.
+ *
+ * @param values - Array of numbers.
+ * @param p - Percentile (0-100).
+ * @returns The percentile value.
+ * @throws {RangeError} If p is outside [0, 100] or array is empty.
+ */
+declare function percentile(values: number[], p: number): number;
+/**
+ * Computes the Pearson correlation coefficient between two arrays.
+ *
+ * @param x - First array.
+ * @param y - Second array.
+ * @returns The correlation coefficient (-1 to 1).
+ * @throws {RangeError} If arrays have different lengths or fewer than 2 pairs.
+ */
+declare function correlation(x: number[], y: number[]): number;
+/**
+ * Formats a number as a currency string with locale support.
+ *
+ * @example formatCurrency(1500000) // "Rp1.500.000"
+ * @example formatCurrency(1500000, { notation: 'compact' }) // "Rp1,5 jt"
+ * @example formatCurrency(99.99, { locale: 'en-US', currency: 'USD' }) // "$99.99"
+ *
+ * @param value - The number to format.
+ * @param options - Formatting options.
+ * @returns The formatted currency string.
+ */
+declare function formatCurrency(value: number, options?: {
+    locale?: string;
+    currency?: string;
+    notation?: 'standard' | 'compact';
+}): string;
+/**
+ * Checks if a number is even.
+ *
+ * @example isEven(4) // true
+ * @example isEven(7) // false
+ *
+ * @param n - The number to check.
+ * @returns Whether the number is even.
+ */
+declare function isEven(n: number): boolean;
+/**
+ * Checks if a number is odd.
+ *
+ * @example isOdd(3) // true
+ * @example isOdd(8) // false
+ *
+ * @param n - The number to check.
+ * @returns Whether the number is odd.
+ */
+declare function isOdd(n: number): boolean;
+/**
+ * Computes the greatest common divisor (GCD) using the Euclidean algorithm.
+ *
+ * @example gcd(12, 8) // 4
+ * @example gcd(17, 5) // 1
+ *
+ * @param a - First integer.
+ * @param b - Second integer.
+ * @returns The GCD.
+ */
+declare function gcd(a: number, b: number): number;
+/**
+ * Computes the least common multiple (LCM).
+ *
+ * @example lcm(4, 6) // 12
+ * @example lcm(7, 5) // 35
+ *
+ * @param a - First integer.
+ * @param b - Second integer.
+ * @returns The LCM.
+ * @throws {RangeError} If either argument is zero.
+ */
+declare function lcm(a: number, b: number): number;
+/**
+ * Computes the factorial of a non-negative integer.
+ *
+ * @example factorial(5) // 120
+ * @example factorial(0) // 1
+ *
+ * @param n - Non-negative integer.
+ * @returns The factorial.
+ * @throws {RangeError} If n is negative or not an integer.
+ */
+declare function factorial(n: number): number;
+/**
+ * Tests whether a number is prime (optimized trial division).
+ *
+ * @example isPrime(7) // true
+ * @example isPrime(10) // false
+ *
+ * @param n - Positive integer.
+ * @returns Whether the number is prime.
+ * @throws {RangeError} If n is not an integer or is less than 2.
+ */
+declare function isPrime(n: number): boolean;
+/**
+ * Converts degrees to radians.
+ *
+ * @example toRadians(180) // ~3.14159
+ *
+ * @param degrees - Angle in degrees.
+ * @returns Angle in radians.
+ */
+declare function toRadians(degrees: number): number;
+/**
+ * Converts radians to degrees.
+ *
+ * @example toDegrees(Math.PI) // 180
+ *
+ * @param radians - Angle in radians.
+ * @returns Angle in degrees.
+ */
+declare function toDegrees(radians: number): number;
+/**
+ * Linearly interpolates between `a` and `b` by `t`.
+ *
+ * @example lerp(0, 100, 0.5) // 50
+ *
+ * @param a - Start value.
+ * @param b - End value.
+ * @param t - Interpolation factor (typically 0–1).
+ * @returns The interpolated value.
+ */
+declare function lerp(a: number, b: number, t: number): number;
+/**
+ * Calculates what percentage `value` is of `total`.
+ *
+ * @example percentageOf(25, 200) // 12.5
+ *
+ * @param value - The part value.
+ * @param total - The total value.
+ * @returns The percentage.
+ * @throws {RangeError} If total is zero.
+ */
+declare function percentageOf(value: number, total: number): number;
+/**
+ * Maps a value from one range to another.
+ *
+ * @example mapRange(0.5, 0, 1, 0, 100) // 50
+ *
+ * @param value - The value to map.
+ * @param inMin - Lower bound of the input range.
+ * @param inMax - Upper bound of the input range.
+ * @param outMin - Lower bound of the output range.
+ * @param outMax - Upper bound of the output range.
+ * @returns The mapped value.
+ * @throws {RangeError} If the input range is zero.
+ */
+declare function mapRange(value: number, inMin: number, inMax: number, outMin: number, outMax: number): number;
+/**
+ * Computes the statistical mode(s) — the most frequently occurring value(s).
+ *
+ * @example mode([1, 2, 2, 3]) // [2]
+ * @example mode([1, 1, 2, 2]) // [1, 2]
+ *
+ * @param values - Array of numbers.
+ * @returns Array of mode value(s).
+ * @throws {RangeError} If the array is empty.
+ */
+declare function mode(values: number[]): number[];
+/**
+ * Generates an array of numbers from `start` to `end` (inclusive),
+ * incremented by `step`.
+ *
+ * @example range(1, 5) // [1, 2, 3, 4, 5]
+ * @example range(0, 10, 2) // [0, 2, 4, 6, 8, 10]
+ *
+ * @param start - Start of the range.
+ * @param end - End of the range (inclusive).
+ * @param step - Increment (defaults to 1 or -1 based on direction).
+ * @returns Array of numbers.
+ * @throws {RangeError} If step is zero.
+ */
+declare function range(start: number, end: number, step?: number): number[];
+/**
+ * Computes the weighted mean of values with corresponding weights.
+ *
+ * @example weightedAverage([10, 20], [1, 4]) // 18
+ *
+ * @param values - Array of values.
+ * @param weights - Array of weights.
+ * @returns The weighted average.
+ * @throws {RangeError} If arrays are empty, differ in length, or sum of weights is zero.
+ */
+declare function weightedAverage(values: number[], weights: number[]): number;
+/**
+ * Computes the geometric mean of an array of numbers.
+ *
+ * @example geometricMean([4, 9]) // 6
+ *
+ * @param values - Array of positive numbers.
+ * @returns The geometric mean.
+ * @throws {RangeError} If the array is empty or contains negative values.
+ */
+declare function geometricMean(values: number[]): number;
+/**
+ * Computes the number of combinations (n choose k) — selecting k items from n without order.
+ *
+ * @example combinations(5, 2) // 10
+ *
+ * @param n - Total items.
+ * @param k - Chosen items.
+ * @returns The number of combinations.
+ * @throws {RangeError} If n < k, or either is negative / non-integer.
+ */
+declare function combinations(n: number, k: number): number;
+/**
+ * Computes the number of permutations — selecting k items from n in order.
+ *
+ * @example permutations(5, 2) // 20
+ *
+ * @param n - Total items.
+ * @param k - Chosen items.
+ * @returns The number of permutations.
+ * @throws {RangeError} If n < k, or either is negative / non-integer.
+ */
+declare function permutations(n: number, k: number): number;
+
+export { DivisionByZeroError, add, approxEqual, average, ceil, clamp, combinations, correlation, div, factorial, floor, formatCurrency, gcd, geometricMean, inRange, isEven, isOdd, isPrime, lcm, lerp, mapRange, median, mode, mul, percentageOf, percentile, permutations, randomInt, range, round, sampleStddev, stddev, sub, sum, toDegrees, toRadians, weightedAverage };