HyperMath is a simple JavaScript/TypeScript library designed to address common pitfalls in JavaScript math operations. It provides a set of static methods for basic arithmetic operations with improved precision and robust error handling.
npm install hypermathimport { HyperMath } from 'hypermath';
// Multiplication
console.log(HyperMath.multiply(0.1, 0.2)); // 0.02 (instead of 0.020000000000000004)
// Addition
console.log(HyperMath.add(0.1, 0.2)); // 0.3 (instead of 0.30000000000000004)
console.log(HyperMath.add(1, 2, 3, 4, 5)); // 15 (supports multiple values!)
// Division
console.log(HyperMath.divide(0.3, 0.1)); // 3 (instead of 2.9999999999999996)
// Subtraction
console.log(HyperMath.subtract(0.3, 0.1)); // 0.2 (instead of 0.19999999999999998)
console.log(HyperMath.subtract(100, 10, 5, 2)); // 83 (supports multiple values!)
// Format a number
console.log(HyperMath.formatNumber(1.12345)); // 1.12
// String inputs are supported
console.log(HyperMath.multiply('10.5', '2.5')); // 26.25The library now throws HyperMathError for invalid inputs:
import { HyperMath, HyperMathError } from 'hypermath';
try {
HyperMath.add(null, 5); // Throws HyperMathError
} catch (error) {
if (error instanceof HyperMathError) {
console.error(error.message); // "Invalid input provided: null"
}
}
// Invalid string inputs also throw errors
HyperMath.multiply('abc', '123'); // Throws HyperMathError: "Invalid input provided: abc"
// Division by zero throws an error
HyperMath.divide(10, 0); // Throws HyperMathError: "Division by zero is not allowed"- Precision handling: Maintains precision up to 2 decimal places using
.toFixed(2) - Flexible inputs: Handles both number and string inputs seamlessly
- Robust error handling: Throws descriptive
HyperMathErrorexceptions for invalid inputs - Edge case protection: Proper handling of division by zero and invalid operations
- Variadic parameters:
add()andsubtract()support multiple values - TypeScript support: Full TypeScript definitions included
- Zero dependencies: Lightweight with no external dependencies
- Comprehensive tests: 81+ unit tests ensuring reliability
Multiplies two numbers with improved precision.
Parameters:
firstValue: Number or string to multiplysecondValue: Number or string to multiply
Returns: The product rounded to 2 decimal places
Throws: HyperMathError if inputs are invalid (null, undefined, or non-numeric strings)
Adds multiple numbers with improved precision.
Parameters:
...values: Two or more numbers or strings to add
Returns: The sum rounded to 2 decimal places
Throws: HyperMathError if fewer than 2 values provided or any input is invalid
Examples:
HyperMath.add(1, 2); // 3
HyperMath.add(1, 2, 3, 4, 5); // 15
HyperMath.add(0.1, 0.2, 0.3); // 0.6
HyperMath.add('10.5', 2.3, '5.2'); // 18Divides two numbers with improved precision.
Parameters:
firstValue: Dividend (number or string)secondValue: Divisor (number or string)
Returns: The quotient rounded to 2 decimal places
Throws:
HyperMathErrorif inputs are invalidHyperMathErrorwith message "Division by zero is not allowed" if divisor is 0
Subtracts multiple numbers with improved precision. The first value minus all subsequent values (left-to-right).
Parameters:
...values: Two or more numbers or strings to subtract
Returns: The difference rounded to 2 decimal places
Throws: HyperMathError if fewer than 2 values provided or any input is invalid
Examples:
HyperMath.subtract(10, 3); // 7
HyperMath.subtract(100, 10, 5, 2); // 83 (100 - 10 - 5 - 2)
HyperMath.subtract(10, 0.1, 0.1, 0.1); // 9.7
HyperMath.subtract('50.5', 10.2, '5.3'); // 35Formats a number to maintain precision up to 2 decimal places.
Parameters:
number: Number or string to format
Returns: The formatted number rounded to 2 decimal places
Throws: HyperMathError if input is invalid
In previous versions (v0.0.x), invalid inputs would silently return 0 with a console warning. Now, errors are thrown for better error handling and debugging.
Old Behavior (v0.0.x):
HyperMath.multiply('invalid', 5); // Returned 0 (with console warning)
HyperMath.divide(10, 0); // Returned 0New Behavior (v0.1.0+):
HyperMath.multiply('invalid', 5); // Throws HyperMathError ❌
HyperMath.divide(10, 0); // Throws DivisionByZeroError ❌Wrap operations in try-catch blocks where invalid input is possible:
// Before (v0.0.x) - unsafe
const result = HyperMath.multiply(userInput, 5);
// After (v0.1.0+) - safe
try {
const result = HyperMath.multiply(userInput, 5);
// Use result...
} catch (error) {
if (error instanceof HyperMathError) {
console.error('Invalid input:', error.message);
// Handle error appropriately
}
}See CHANGELOG.md for complete migration guide.
- Precision: This library uses
.toFixed(2)internally to maintain precision up to 2 decimal places. This may lead to rounding in some cases. Be aware of this limitation when using the library for calculations requiring higher precision. - Error handling: The library now throws
HyperMathErrorexceptions instead of returning 0 for invalid inputs. Make sure to handle these errors appropriately in your code. - Edge cases:
- Division by zero: Throws
DivisionByZeroErrorinstead of returning 0 - Invalid inputs: Any null, undefined, or non-numeric string values will throw
HyperMathError - String parsing: String inputs are validated using
Number()to ensure the entire string is numeric. Strings with trailing non-numeric characters (e.g.,"123abc") will throwHyperMathError
- Division by zero: Throws
- Type safety: TypeScript users benefit from full type definitions and the custom
HyperMathErrorclass for better error handling
If you encounter any issues or have questions, please open an issue on the GitHub repository.
Contributions are welcome! Please feel free to submit a Pull Request.
This project is licensed under the MIT License - see the LICENSE file for details.