Support for arbitrarily large integers (BigInts) is a stage 3 TC39 proposal. Stage 3 means the proposal is ready and for browsers to start implementing. Earlier this year, the V8 team added support for BigInts, which means Node.js 10.4.0 has BigInt support. You can use BigInts in Node.js 10.x without any flags, as long as you're on at least 10.4.

$ ~/Workspace/libs/node-v10.4.0-linux-x64/bin/node --version v10.4.0 $ ~/Workspace/libs/node-v10.4.0-linux-x64/bin/node > 10000000000n * 10000000000n 100000000000000000000n >

What Are BigInts?

BigInt is a new JavaScript primitive type that can store arbitrarily large integers, like the Busy Beaver sequence or values of the Ackermann sequence. You can store arbitrarily large numbers as strings, but BigInts have the benefit of supporting arithmetic operators. In other words, you can add and multiply BigInts like you would normal numbers.

There are 2 ways to create a BigInt: either by appending 'n' at the end of an integer literal, or by using the BigInt() constructor:

42 n; BigInt( '42' ); BigInt( 42 );

BigInts are not numbers, they are a completely new type. They're the first new primitive type added to JavaScript since Symbols in ES2015. In Node.js 10.4, the primitive data types are:

Boolean

Null

Undefined

Number

String

Symbol

BigInt

To check if a value is a BigInt, you can use the typeof operator.

typeof 42 n;

BigInt equality is strictly by value.

const x = 42 n; let y = 42 n; x === y; ++y; x === y;

Arithmetic On BigInts

The + , * , - , ** , and % operators work as you would expect between 2 BigInts. You can also use ++ and -- as you would with numbers.

5 n + 3 n; 5 n * 3 n; 5 n - 3 n; 5 n ** 3 n; 5 n % 3 n; let x = 1 ; ++x; x++; x--;

Division, the / operator, is slightly trickier. BigInts are always integers, and the TC39 spec says that BigInt division always rounds down. So even though 5 / 3 is approximately 1.6666 , 5n / 3n === 1n ;

Arithmetic operators between BigInts and numbers do not work. Multiplying a BigInt by a number throws an error.

5 n + 3 ; 5 n * 3 ; 5 - 3 n; 5 ** 3 n; 5 % 3 n;

Comparisons, like > , >= , < , and <= , work as you would expect, even when comparing BigInts to numbers.

42 n > 42 ; 42 n >= 42 ; 43 n > 42 ; 42 n < 43 ; 42 n <= 42 ; 42 n == 42 ; 42 n === 42 ;

Currently, JavaScripts Math utility functions do not support BigInts. While you can use the exponentiation operator ** , using Math.pow() throws an error:

Math .pow( 5 n, 3 n);

Limitations

There are several limitations to using BigInts. Because BigInts are a new primitive type, many existing libraries and frameworks do not support them. Currently, you can't even JSON.stringify() an object that contains a BigInt.

JSON .stringify({ answer: 42 n });

To work around this limitation, you can add a toJSON() function to BigInt's prototype:

BigInt.prototype.toJSON = function ( ) { return this .toString(); }; JSON .stringify({ answer: 42 n });

Similarly, the MongoDB driver and Mongoose currently do not support BigInts. The MongoDB driver will silently ignore properties whose values are BigInts.

const { MongoClient } = require ( 'mongodb' ); run().catch(error => console .error(error.stack)); async function run ( ) { const client = await MongoClient.connect( 'mongodb://localhost:27017/test' , { useNewUrlParser: true }); const db = client.db(); await db.dropDatabase(); await db.collection( 'BigInt' ).insertOne({ answer: 42 n }); const res = await db.collection( 'BigInt' ).findOne(); console .log(res); }

Currently the only workaround for this is to add a toBSON() function to BigInt.prototype . This will tell the MongoDB driver to convert the BigInt to a string before storing it in MongoDB.

const { MongoClient } = require ( 'mongodb' ); run().catch(error => console .error(error.stack)); async function run ( ) { const client = await MongoClient.connect( 'mongodb://localhost:27017/test' , { useNewUrlParser: true }); const db = client.db(); await db.dropDatabase(); BigInt.prototype.toBSON = function ( ) { return this .toString(); }; await db.collection( 'BigInt' ).insertOne({ answer: 42 n }); const res = await db.collection( 'BigInt' ).findOne(); console .log(res); }

React doesn't currently support passing in BigInts as a child to React.createElement() either:

const { renderToString } = require ( 'react-dom/server' ); const { createElement, Component } = require ( 'react' ); class MyComponent extends Component { render() { return createElement( 'h1' , null , 42 n); } } console .log(renderToString(createElement(MyComponent)));

Moving On