@js-augment/bigint

v2026.1.21

Published

6 days ago

A security-focused, tree-shakeable TypeScript library for robust BigInt validation and manipulation. Built with modern best practices, strict runtime checks, and high-performance type guards—fully browser-compatible and designed to safely handle edge case

Downloads

Switch to German

`@js-augment/bigint`

NPM version

Easy to use as global extension for JavaScript's BigInt:

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

BigInt.isGreater(10n, 20n); // false
BigInt.Strict.isOdd(11n); // true

Or as local functions:

import { isBigIntGreater, strictBigIntIsOdd } from "@js-augment/bigint";

isBigIntGreater(10n, 20n); // false
strictBigIntIsOdd(11n); // true

What is @js-augment/bigint?

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

The library includes over 50 functions, for example, for data manipulation (bigIntClamp, ...), various type guards from range and content checking to number classification (isBigIntBetween, isBigIntPositive, ...), safe size comparisons with type checking in the background (isBigIntGreaterOrEqual, isBigIntMaximum, ...), property checks (isBigIntEven, isBigIntOdd, ...) and many more.

Why should I use @js-augment/bigint?

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 BigInt object and the BigInt.Strict namespace.
Maximum tree shaking: With functional import, only the functions you actually use end up in the bundle.

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

Global Augmentation

It enhances the native BigInt object and the new BigInt.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/bigint is optimized from the ground up for maximum tree shaking. If the functions are not bound to the global BigInt object but imported as individual modules (e.g., import {strictBigIntCeil} from '@js-augment/bigint'), 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/bigint 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/bigint supports all modern browsers, including Chrome, Edge, Firefox, Opera, and Safari.

How do I use @js-augment/bigint?

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/bigint, use the following command in the command line:

npm install @js-augment/bigint

package.json

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

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

tsconfig.json

Since @js-augment/bigint 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 {isBigInt} from "@js-augment/bigint";

isBigInt(1337); // true

Global object import

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

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

BigInt.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/bigint/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/bigint can be loaded via the Content Delivery Network (CDN) jsDelivr or unpkg:

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

  console.log(isBigIntEven(1337n)); // false

  const min = 3n;
  const max = 10n;
  const inklusive = true;
  console.log(isBigIntBetween(5n, min, max, inklusive)); // true
</script>

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

Usage

The library is designed to be used both functionally (for maximum tree shaking) and via the global BigInt 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 null 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., strictIsBigIntOdd) or are located in the namespace BigInt.Strict (global).

import { bigIntLerp, strictBigIntLerp, bigIntIsBetween, bigIntIsPrime } from "@js-augment/bigint";

// Lenient: Returns null on invalid types or logical errors
// (null is used as the big integer equivalent for "no result" since NaN does not exist)
console.log(bigIntLerp(0n, 100n, "half" as any)); // null

console.log(bigIntIsBetween(42n, 10n, 50n)); // true
console.log(bigIntIsPrime(13n)); // true

// Strict: Throws an error (ideal for development & debugging)
// Throws TypeError: [BigInt.Strict.lerp] "start" must be a bigint.
strictBigIntLerp(0 as any, 100n, 50n);

// Throws RangeError: [BigInt.Strict.isBetween] "end" must be greater than "start".
strictBigIntIsBetween(5n, 100n, 10n);

Examples

Sample data

const transaction = { 
 id: 9223372036854775807n, // Große 64-Bit ID (BigInt)
 amountInCents: 15000000n, // Betrag in Cent
 timestamp: 1705756800000n,
 metadata: {
  priority: 5n
 }
};

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 { bigIntHasBigInt, bigIntIsPositive, bigIntClamp, strictBigIntIsPrime } from "@js-augment/bigint";

function processTransaction(data)
{
  // Ensure ID is positive.
  if (!bigIntIsPositive(data.id))
    throw new TypeError("Invalid Transaction ID");

  // Check if the ID contains a specific sequence.
  if (bigIntHasBigInt(data.id, "775")) {
    console.log("Special ID sequence detected.");
  }

  // Clamp the amount within a safe range.
  const safeAmount = bigIntClamp(data.amountInCents, 0n, 1000000000n);

  // Strictly check if priority is a prime number.
  if (strictBigIntIsPrime(data.metadata.priority)) {
    console.log("Priority is a prime number.");
  }
}

processTransaction(transaction);

Example with global augmentation

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

import "@js-augment/bigint/register-global";

function processTransaction(data)
{
  // Direct access via the global BigInt object.
  if (!BigInt.isPositive(data.id))
    throw new TypeError("Invalid Transaction ID");

  // The 'clamp' method is now available globally.
  const safeAmount = BigInt.clamp(data.amountInCents, 0n, 1000000000n);

  // Accessing the Strict namespace.
  if (BigInt.Strict.isPrime(data.metadata.priority)) {
    console.log("Priority is a prime number.");
  }
}

processTransaction(transaction);

Functions / Methods

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

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

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

Example:

isBigIntEven becomes BigInt.isEven(42)
strictIsBigIntEven becomes BigInt.Strict.isEven(42)

Transformation

Manipulation

| Function (lenient) | Strict | Global | Global (Strict) | |--------------------------------------------------------|:------------------:|:-------------:|:--------------------:| | bigIntClamp(value, min, max) | strictBigIntClamp | BigInt.clamp | BigInt.Strict.clamp | | bigIntLerp(start, end, amount) | strictBigIntLerp | BigInt.lerp | BigInt.Strict.lerp | | bigIntModulo(value, divisor) | strictBigIntModulo | BigInt.modulo | BigInt.Strict.modulo | | bigIntWrap(value, min, max) | strictBigIntWrap | BigInt.wrap | BigInt.Strict.wrap |

Comparison & Validation

Equality

| Function (lenient) | Strict | Global | Global (Strict) | |----------------------------------------------------------|:--------------------:|:---------------:|:----------------------:| | bigIntEquals(value, other) | strictBigIntEquals | BigInt.equals | BigInt.Strict.equals | | bigIntUnequals(value, other) | strictBigIntUnequals | BigInt.unequals | BigInt.Strict.unequals |

Size comparisons

| Function (lenient) | Strict | Global | Global (Strict) | |------------------------------------------------------------------------------|:----------------------------:|:-----------------------:|:------------------------------:| | isBigIntGreater(value, threshold) | strictIsBigIntGreater | BigInt.isGreater | BigInt.Strict.isGreater | | isBigIntGreaterOrEqual(value, threshold) | strictIsBigIntGreaterOrEqual | BigInt.isGreaterOrEqual | BigInt.Strict.isGreaterOrEqual | | isBigIntLess(value, threshold) | strictIsBigIntLess | BigInt.isLess | BigInt.Strict.isLess | | isBigIntLessOrEqual(value, threshold) | strictIsBigIntLessOrEqual | BigInt.isLessOrEqual | BigInt.Strict.isLessOrEqual | | isBigIntMaximum(value, maximum) | strictIsBigIntMaximum | BigInt.isMaximum | BigInt.Strict.isMaximum | | isBigIntMinimum(value, minimum) | strictIsBigIntMinimum | BigInt.isMinimum | BigInt.Strict.isMinimum |

Property check

| Function (lenient) | Strict | Global | Global (Strict) | |-----------------------------------------------------------------|:------------------------:|:-------------------:|:--------------------------:| | isBigIntEven(value) | strictIsBigIntEven | BigInt.isEven | BigInt.Strict.isEven | | isBigIntMultipleOf(value, base) | strictIsBigIntMultipleOf | BigInt.isMultipleOf | BigInt.Strict.isMultipleOf | | isBigIntOdd(value) | strictIsBigIntOdd | BigInt.isOdd | BigInt.Strict.isOdd | | isBigIntPowerOf(value, base) | strictIsBigIntPowerOf | BigInt.isPowerOf | BigInt.Strict.isPowerOf |

Type Guards

Ranges and Content Checks

| Function (lenient) | Strict | Global | Global (Strict) | |----------------------------------------------------------------------------|:---------------------:|:----------------:|:-----------------------:| | hasBigInt(value, has) | strictHasBigInt | BigInt.hasBigInt | BigInt.Strict.hasBigInt | | isBigIntBetween(value, start, end, inclusive) | strictIsBigIntBetween | BigInt.isBetween | BigInt.Strict.isBetween | | isBigIntIn(value, list) | strictIsBigIntIn | BigInt.isIn | BigInt.Strict.isIn |

BigInt Classification

| Function (lenient) | Strict | Global | Global (Strict) | |-------------------------------------------------------------|:-------------------------:|:--------------------:|:---------------------------:| | isBigInt(value) | - | BigInt.isBigInt | - | | isBigIntNegative(value) | strictIsBigIntNegative | BigInt.isNegative | BigInt.Strict.isNegative | | isBigIntNonNegative(value) | strictIsBigIntNonNegative | BigInt.isNonNegative | BigInt.Strict.isNonNegative | | isBigIntNonPositive(value) | strictIsBigIntNonPositive | BigInt.isNonPositive | BigInt.Strict.isNonPositive | | isBigIntNonZero(value) | strictIsBigIntNonZero | BigInt.isNonZero | BigInt.Strict.isNonZero | | isBigIntPositive(value) | strictIsBigIntPositive | BigInt.isPositive | BigInt.Strict.isPositive | | isBigIntPrime(value) | strictIsBigIntPrime | BigInt.isPrime | BigInt.Strict.isPrime |

String literals

In JavaScript, passing any kind of number directly 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) | |-------------------------------------------------------------|:-------------------:|:--------------------:|:---------------------------:| | isBigIntBinary(value) | strictIsBinary | BigInt.isBinary | BigInt.Strict.isBinary | | isBigIntHexadecimal(value) | strictIsHexadecimal | BigInt.isHexadecimal | BigInt.Strict.isHexadecimal | | isBigIntOctal(value) | strictIsOctal | BigInt.isOctal | BigInt.Strict.isOctal |

If import from "register-globals.mjs is used, the global object BigInt is extended. This means that, in addition to the new methods, all static methods and properties of BigInt 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.