@js-augment/number

v2026.1.21

Published

7 days ago

A comprehensive TypeScript library for safe number validation and manipulation. Features powerful Type Guards, strict checks, and fixes for native JavaScript limitations.

Switch to German

`@js-augment/number`

NPM version

Easy to use (functional import):

import { isFloat, strictCeil } from "@js-augment/number";

isFloat(1337); // false
strictCeil(10.2, 1); // 11

Or as a global extension:

import "@js-augment/number/register-globals.mjs";

Number.isFloat(1337); // false
Number.Strict.ceil(10.2, 1); // 11

What is @js-augment/number?

@js-augment/number is a high-performance, security-focused TypeScript utility library developed specifically for professional developers by Roland Milto to take working with numerical data in JavaScript and TypeScript to a new level.

The library includes over 50 functions, for example for data manipulation (clamp, fraction, ...), various type guards from range and content checking to number classification (isBetween , isPositive, ...), safe size comparisons with type checking in the background (isGreaterOrEqual, isMaximum, ...), property checks (isEven, isOdd, ...) and many more.

Why should I use @js-augment/number?

The library takes two complementary approaches, offering significant advantages:

Professional TypeScript: The library provides first-class typing, uses type predicates for intelligent type narrowing, and offers assertion functions for maximum safety at development time.
Performance-optimized: Every function is tuned for speed (e.g., bitwise operations for powers of two or optimized prime number algorithms) without compromising mathematical correctness.
Security-Oriented: Dual mode (lenient vs. strict) allows you to choose between error-tolerant calculations (returning NaN) and hard security checks (exceptions), which is ideal for TDD and mission-critical applications.
Global augmentation: Seamlessly enhances the native Number object and the Number.Strict namespace.
Maximum tree shaking: With functional import, only the functions you actually use end up in the bundle.

In summary, @js-augment/number is the Swiss Army knife for numerical operations, combining the flexibility of functional programming with the elegance of global language extensions.

Global Augmentation

It enhances the native Number object and the new Number.Strict namespace with over 50 powerful mathematical operations, type guards, and validations. By integrating into the global object, the library feels like a native part of the language, but offers uncompromising runtime validation through strict mode, which immediately throws errors when invalid data is processed.

Functional Design and Tree Shaking

For modern web applications where every kilobyte counts, @js-augment/number is optimized from the ground up for maximum tree shaking. If the functions are not bound to the global Number object but imported as individual modules (e.g., import { strictCeil } from ‘@js-augment/number’), only those functions that are actually used end up in the final bundle. Ballast is completely removed by the bundler (such as Vite, Webpack, or Rollup).

Excellent for design-time testing

Although optimized for runtime, @js-augment/number is the perfect addition to your test suites:

Use the same valid check mechanisms in your unit tests as in your production logic.
No need for complex configuration of test runners—the guards work everywhere: Node.js, browsers, edge runtimes, or serverless functions.

Browser Support

@js-augment/number supports all modern browsers, including Chrome, Edge, Firefox, Opera, and Safari.

How do I use @js-augment/number?

Prerequisites

The package is designed as a native ES module (ESM) and supports all modern environments from ES2020+ (Node.js 18+, current browsers, and Edge runtimes) to ensure maximum efficiency without unnecessary polyfills.

Installation

To install @js-augment/number, use the following command in the command line:

npm install @js-augment/number

package.json

Ensure that @js-augment/number is included in your package.json dependencies and that the latest version is always used:

{
 "dependencies": {
  "@js-augment/number": "*"
 }
}

tsconfig.json

Since @js-augment/number is exported as an ESM module, it is necessary to adjust the moduleResolution option in the tsconfig.json file to avoid error messages from the TypeScript compiler:

{
 "compilerOptions": {
  "moduleResolution": "NodeNext"
 }
}

Import

Local function import

Individual import of single functions (recommended for tree shaking):

import {isNumber} from "@js-augment/number";

isNumber(1337); // true

Global object import

Use @js-augment/number as a global import for all functions via the Number object, so you only need to include the library once in your project:

import "@js-augment/number/register-global.mjs";

Number.isOdd(7); // true

If your IDE does not automatically recognize the types, you can manually register the types in tsconfig.json:

{
 "compilerOptions": {
  "types": [
   "@js-augment/number/register-global"
  ]
 }
}

Browser Import

If the bundle is to be hosted locally, the minified bundle can be found at dist/index.min.mjs in the package directory.

For quick integration into prototypes or direct use in the browser (without a build step), @js-augment/number can be loaded via the Content Delivery Network (CDN) jsDelivr or unpkg:

<script type="module">
 import {isFloat, isIntegerBetween} from "https://cdn.jsdelivr.net/npm/@js-augment/number/dist/index.min.mjs";

 console.log(isFloat(1337)); // false
 
 const min = 3;
 const max = 10;
 const inclusive = true;
 console.log(isIntegerBetween(5, min, max, inclusive)); // true
</script>

For unpkg, use this URL: https://unpkg.com/@js-augment/number/dist/index.min.mjs

Usage

The library is designed to be used both functionally (for maximum tree shaking) and via the global Number object.

All functions take the value to be checked or processed as their first argument. Many mathematical functions (such as ceil, modulo, or isBetween) accept additional parameters to control the operation (e.g., step size or limits).

There are two modes available:

Lenient (default): Lenient; returns NaN or false for invalid inputs.
Strict: Strict; immediately throws a TypeError or RangeError for invalid parameters. Functions in strict mode have the prefix strict (e.g., strictCeil) or are located in the namespace Number.Strict (global).

import { ceil, strictCeil, isBetween, isPrime } from "@js-augment/number";

// Lenient: Returns NaN on errors (step size 0 is invalid)
console.log(ceil(10.5, 0));

console.log(isBetween(42, 10, 50)); // true
console.log(isPrime(13)); // true

// Strict: Throws an error (ideal for development & debugging) 
// Throws RangeError: [Number.Strict.ceil] step must be a positive integer.
strictCeil(10.5, 0);

Examples

Sample data

const product = { 
 id: 45092, 
 price: 19.9945, 
 stock: 150, 
 dimensions: { 
  weight: 1.2, 
  width: 0.5 
 } 
};

Example with tree-shakable functions

In this mode, only the functions that are actually imported are included in the final project bundle. This is the recommended method for web applications.

import { isInteger, strictToFinancial, clamp, isPositive } from "@js-augment/number";

function processProductData(data) 
{ 
 // Ensure that the ID is an integer.
 if (!isInteger(data.id)) 
  throw new TypeError("Invalid product ID");
  
 // Format the price securely in financial format (2 decimal places).
 const displayPrice = strictToFinancial(data.price);

 // "Price: ${displayPrice}"
 console.log(`Price: ${displayPrice}`);
  
 // Keep stock within a safe range.
 const safeStock = clamp(data.stock, 0, 1000);
 console.log(`Stock (limited): ${safeStock}`);
 
 if (isPositive(data.dimensions.weight)) {
  console.log(`Shipping weight: ${data.dimensions.weight} kg`); 
 } 
}

processProductData(product);

Example with global augmentation

Once the library has been registered (by importing register-global), all functions are directly available on the global Number object. This improves readability and makes the functions available everywhere without explicit import.

import { isInteger, strictToFinancial, clamp, isPositive } from "@js-augment/number";

function processProductData(data) 
{ 
 // Ensure that the ID is an integer .
 if (!Number.isInteger(data.id)) 
  throw new TypeError("Invalid product ID");
  
 // Format price safely to financial format (2 decimal places).
 const displayPrice = Number.Strict.toFinancial(data.price);

 // "Price: ${displayPrice}"
 console.log(`Price: ${displayPrice}`);
  
 // Keep stock within a safe range.
 const safeStock = Number.clamp(data.stock, 0, 1000);
 console.log(`Stock (limited): ${safeStock}`);
 
 if (Number.isPositive(data.dimensions.weight)) {
  console.log(`Shipping weight: ${data.dimensions.weight} kg`); 
 } 
}

processProductData(product);

Functions / Methods

The following overview shows the available functions of @js-augment/number. The first column contains a link to detailed documentation, including the complete signature.

When using register-global with import "@js-augment/number/register-global.mjs", each function can also be called as a method of the global Number object.

The strict variants shown here can be called via Number.Strict.

Example:

isFloat becomes Number.isFloat(1337)
strictIsFloat becomes Number.Strict.isFloat(1337)

Analysis and information

| Function (lenient) | Strict | Global | Global (Strict) | |-----------------------------------------------|:---------------:|:----------------:|:-----------------------:| | getType(value) | strictGetType | Number.getType | Number.Strict.getType | | precision(value) | strictPrecision | Number.precision | Number.Strict.precision |

Transformation and rounding

Rounding

| Function (lenient) | Strict | Global | Global (Strict) | |---------------------------------------------------|:-----------------:|:------------------:|:-------------------------:| | ceil(value, step) | strictCeil | Number.ceil | Number.Strict.ceil | | floor(value, step) | strictFloor | Number.floor | Number.Strict.floor | | round(value, step) | strictRound | Number.round | Number.Strict.round | | toFinancial(value) | strictToFinancial | Number.toFinancial | Number.Strict.toFinancial | | toFixed(value, digits) | strictToFixed | Number.toFixed | Number.Strict.toFixed |

Conversion

| Function (lenient) | Strict | Global | Global (Strict) | |-----------------------------------------------------------------|:-------------------:|:--------------------:|:---------------------------:| | toExponential(value, fraction) | strictToExponential | Number.toExponential | Number.Strict.toExponential | | toPrecision(value, precision) | strictToPrecision | Number.toPrecision | Number.Strict.toPrecision |

Manipulation

| Function (lenient) | Strict | Global | Global (Strict) | |--------------------------------------------------|:--------------:|:---------------:|:----------------------:| | clamp(value, min, max) | strictClamp | Number.clamp | Number.Strict.clamp | | fraction(value) | strictFraction | Number.fraction | Number.Strict.fraction | | lerp(start, end, amount) | strictLerp | Number.lerp | Number.Strict.lerp | | modulo(value, divisor) | strictModulo | Number.modulo | Number.Strict.modulo | | wrap(value, min, max) | strictWrap | Number.wrap | Number.Strict.wrap |

Comparison & Validation

Equality

| Function (lenient) | Strict | Global | Global (Strict) | |----------------------------------------------------|:--------------:|:---------------:|:----------------------:| | equals(value, other) | strictEquals | Number.equals | Number.Strict.equals | | unequals(value, other) | strictUnequals | Number.unequals | Number.Strict.unequals |

Size comparisons

| Function (lenient) | Strict | Global | Global (Strict) | |------------------------------------------------------------------------|:----------------------:|:-----------------------:|:------------------------------:| | isGreater(value, threshold) | strictIsGreater | Number.isGreater | Number.Strict.isGreater | | isGreaterOrEqual(value, threshold) | strictIsGreaterOrEqual | Number.isGreaterOrEqual | Number.Strict.isGreaterOrEqual | | isLess(value, threshold) | strictIsLess | Number.isLess | Number.Strict.isLess | | isLessOrEqual(value, threshold) | strictIsLessOrEqual | Number.isLessOrEqual | Number.Strict.isLessOrEqual | | isMaximum(value, maximum) | strictIsMaximum | Number.isMaximum | Number.Strict.isMaximum | | isMaximumInteger(value, maximum) | strictIsMaximumInteger | Number.isMaximumInteger | Number.Strict.isMaximumInteger | | isMinimum(value, minimum) | strictIsMinimum | Number.isMinimum | Number.Strict.isMinimum | | isMinimumInteger(value, minimum) | strictIsMinimumInteger | Number.isMinimumInteger | Number.Strict.isMinimumInteger |

Property check

| Function (lenient) | Strict | Global | Global (Strict) | |-----------------------------------------------------------|:------------------:|:-------------------:|:--------------------------:| | isEven(value) | strictIsEven | Number.isEven | Number.Strict.isEven | | isMultipleOf(value, base) | strictIsMultipleOf | Number.isMultipleOf | Number.Strict.isMultipleOf | | isOdd(value) | strictIsOdd | Number.isOdd | Number.Strict.isOdd | | isPowerOf(value, base) | strictIsPowerOf | Number.isPowerOf | Number.Strict.isPowerOf |

Type Guards

Ranges and Content Checks

| Function (lenient) | Strict | Global | Global (Strict) | |------------------------------------------------------------------------------------|:----------------------:|:-----------------------:|:------------------------------:| | hasNumber(value, has) | strictHasNumber | Number.hasNumber | Number.Strict.hasNumber | | isBetween(value, start, end, inclusive) | strictIsBetween | Number.isBetween | Number.Strict.isBetween | | isIn(value, list) | strictIsIn | Number.isIn | Number.Strict.isIn | | isIntegerBetween(value, start, end, inclusive) | strictIsIntegerBetween | Number.isIntegerBetween | Number.Strict.isIntegerBetween |

Number Classification

| Function (lenient) | Strict | Global | Global (Strict) | |---------------------------------------------------------------------|:--------------------------:|:---------------------------:|:----------------------------------:| | isBigInt(value) | - | Number.isBigInt | - | | isFloat(value) | strictIsFloat | Number.isFloat | Number.Strict.isFloat | | isNegative(value) | strictIsNegative | Number.isNegative | Number.Strict.isNegative | | isNegativeInteger(value) | strictIsNegativeInteger | Number.isNegativeInteger | Number.Strict.isNegativeInteger | | isNonNegative(value) | strictIsNonNegative | Number.isNonNegative | Number.Strict.isNonNegative | | isNonNegativeInteger(value) | strictIsNonNegativeInteger | Number.isNonNegativeInteger | Number.Strict.isNonNegativeInteger | | isNonPositive(value) | strictIsNonPositive | Number.isNonPositive | Number.Strict.isNonPositive | | isNonPositiveInteger(value) | strictIsNonPositiveInteger | Number.isNonPositiveInteger | Number.Strict.isNonPositiveInteger | | isNonZero(value) | strictIsNonZero | Number.isNonZero | Number.Strict.isNonZero | | isNonZeroInteger(value) | strictIsNonZeroInteger | Number.isNonZeroInteger | Number.Strict.isNonZeroInteger | | isNumber(value) | - | Number.isNumber | - | | isPositive(value) | strictIsPositive | Number.isPositive | Number.Strict.isPositive | | isPositiveInteger(value) | strictIsPositiveInteger | Number.isPositiveInteger | Number.Strict.isPositiveInteger | | isPrime(value) | strictIsPrime | Number.isPrime | Number.Strict.isPrime |

String literals

In JavaScript, directly passing numbers of any kind to variables causes them to be converted internally to normal numbers. It is therefore not possible to check whether the number was specified as an octal number or a hexadecimal number, for example. The check can therefore only be performed using string literals.

| Function (lenient) | Strict | Global | Global (Strict) | |-------------------------------------------------------|:-------------------:|:--------------------:|:---------------------------:| | isBinary(value) | strictIsBinary | Number.isBinary | Number.Strict.isBinary | | isDecimal(value) | strictIsDecimal | Number.isDecimal | Number.Strict.isDecimal | | isHexadecimal(value) | strictIsHexadecimal | Number.isHexadecimal | Number.Strict.isHexadecimal | | isOctal(value) | strictIsOctal | Number.isOctal | Number.Strict.isOctal |

If import from "register-globals.mjs is used, the global object Number is extended. This means that, in addition to the new methods, all static methods and properties of Number are also available.

The @js-augment ecosystem

@js-augment is intended as an extension of @type-check/guards, which checks individual types in even greater detail.

Libraries based on @type-check/guards in the @js-augment namespace:

Support or report bugs

If you would also like to contribute to the library (e.g., translations), you are welcome to do so.

You can find information about this at CONTRIBUTING.md. You will also be mentioned in the AUTHORS.md file.

If you find any bugs or have ideas for useful enhancements, you can contribute directly on GitHub.