{"id":10573,"library":"big-integer","title":"BigInteger.js: Arbitrary-Length Integers","description":"BigInteger.js is a robust JavaScript library for performing arithmetic operations on integers of unlimited size, circumventing JavaScript's standard number precision limitations. The current stable version is 1.6.52. While releases are not on a fixed schedule, the project is actively maintained, with recent updates addressing various fixes and TypeScript definitions. A key differentiator and recent major change is its evolution into a polyfill for the native JavaScript `BigInt` feature (introduced to TC39 in 2018). If the execution environment supports native `BigInt`, this library will transparently wrap the native implementation, otherwise, it provides its own software-based arbitrary-length integer solution. This makes it a highly compatible choice for environments with varying `BigInt` support.","status":"active","version":"1.6.52","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/peterolson/BigInteger.js","tags":["javascript","math","big","bignum","bigint","biginteger","integer","arbitrary","precision","typescript"],"install":[{"cmd":"npm install big-integer","lang":"bash","label":"npm"},{"cmd":"yarn add big-integer","lang":"bash","label":"yarn"},{"cmd":"pnpm add big-integer","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary `bigInt` factory function is the default export of the package for ESM. Named import `{ bigInt }` is incorrect.","wrong":"import { bigInt } from 'big-integer';","symbol":"bigInt","correct":"import bigInt from 'big-integer';"},{"note":"In CommonJS, the `bigInt` factory function is the default export. Destructuring `bigInt` from `require('big-integer')` is incorrect.","wrong":"const { bigInt } = require('big-integer');","symbol":"bigInt (CommonJS)","correct":"const bigInt = require('big-integer');"},{"note":"Since v1.6.22, TypeScript definitions are included. Use `import type` for the `BigInteger` interface if you are only importing the type.","wrong":"import { BigInteger } from 'big-integer';","symbol":"BigInteger (Type)","correct":"import type { BigInteger } from 'big-integer';"}],"quickstart":{"code":"import bigInt from 'big-integer';\n\nfunction calculateFactorial(n: number): bigInt.BigInteger {\n  let result = bigInt.one;\n  for (let i = 2; i <= n; i++) {\n    result = result.times(i);\n  }\n  return result;\n}\n\n// Calculate factorial of a moderately large number\nconst numberToFactorial = 50;\nconst factorialResult = calculateFactorial(numberToFactorial);\nconsole.log(`Factorial of ${numberToFactorial} is: ${factorialResult.toString()}`);\n\n// Demonstrating operations with large string inputs to avoid JS number precision limits\nconst largeA = bigInt('123456789012345678901234567890');\nconst largeB = bigInt('987654321098765432109876543210');\nconst sum = largeA.plus(largeB);\nconsole.log(`Sum of two large numbers: ${sum.toString()}`);\n\n// Accessing pre-stored constants\nconsole.log(`Zero: ${bigInt.zero.toString()}`);\nconsole.log(`One: ${bigInt.one.toString()}`);\nconsole.log(`Minus One: ${bigInt.minusOne.toString()}`);\n\n// Note: The actual type of `factorialResult` might be native `BigInt` or `BigInteger` object\n// depending on environment support and library's polyfill behavior.\n","lang":"typescript","description":"This quickstart demonstrates how to initialize `bigInt` values from numbers and strings, perform arithmetic operations like factorial calculation, and use pre-defined constants, highlighting its use in handling large integer arithmetic beyond standard JavaScript number limits."},"warnings":[{"fix":"Prefer using `bigInt.isInstance(value)` for checking if a value is a big-integer managed type. Avoid `instanceof` or direct type checking if cross-compatibility with native `BigInt` is required.","message":"Starting with v1.6.37, `big-integer` acts as a polyfill for the native JavaScript `BigInt`. If the environment supports native `BigInt`, the library internally uses and often returns native `BigInt` instances. This can lead to unexpected behavior when using `instanceof` checks (e.g., `value instanceof bigInt.BigInteger`) or strict type comparisons, as the returned objects might be native `BigInt` primitives.","severity":"breaking","affected_versions":">=1.6.37"},{"fix":"Always pass large integer values as strings to the `bigInt()` factory function to ensure exact representation and avoid precision loss. For example, `bigInt('9007199999999999')` instead of `bigInt(9007199999999999)`.","message":"JavaScript numbers have a maximum safe integer limit (`Number.MAX_SAFE_INTEGER`). Passing numbers larger than `9007199254740992` or smaller than `-9007199254740992` directly to `bigInt()` will result in loss of precision, as JavaScript itself cannot precisely represent these values.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Evaluate your project's target environment support. If native `BigInt` is available, consider using `n` suffix for literals (e.g., `123n`) and native operations. If broader compatibility is needed or older environments must be supported, `big-integer` remains a viable polyfill.","message":"With the widespread adoption of native `BigInt` in modern JavaScript environments, for new projects targeting environments with `BigInt` support, it is generally recommended to use native `BigInt` directly rather than relying on polyfill libraries like `big-integer` for simple arithmetic.","severity":"deprecated","affected_versions":">=1.6.37"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure that string inputs only contain valid digits for the specified base and that the base parameter itself is a valid integer. For example, `bigInt('hello')` will throw this error, as will `bigInt('10', 0)`.","cause":"Attempting to create a `bigInt` from a string or number that cannot be parsed as a valid integer, or providing a base that is not a valid `bigInt`.","error":"Error: Invalid integer"},{"fix":"When `big-integer` uses native `BigInt` as a polyfill, all operands in an arithmetic operation must be `BigInt`s. Convert standard numbers to `BigInt` using `BigInt(number)` or `bigInt(number)` before operations, e.g., `bigInt('100').plus(bigInt(5))` instead of `bigInt('100').plus(5)`.","cause":"This error occurs when trying to perform operations between a native `BigInt` (which `big-integer` might return as a polyfill) and a standard JavaScript `Number` or other type, without explicit conversion.","error":"TypeError: Cannot mix BigInt and other types, use explicit conversions"}],"ecosystem":"npm"}