Compile ints to big-ints on the Javascript target

[abs0luty]

Current design

On the BEAM target, Int values are arbitrary-precision integers (limited only by memory). Small integers are optimized; larger ones transparently become bignums. Float is the runtime's 64-bit IEEE-754 double, but BEAM has no NaN/Infinity values exposed in the same way as JavaScript.

On the JavaScript target, Float is a 64-bit IEEE-754 double, matching JS Number. Int operations obey the host's numeric semantics; keep integers within JS's safe integer range (±(2^53−1)) to avoid precision loss, or use library types/BigInt when you need larger exact integers.

import gleam/io
import gleam/int

fn main() {
  io.println(9_999_999_999_999_999 |> int.to_string)
}

Output when running the code using default erlang target (gleam run):

9999999999999999

Output when running the code using javascript target (gleam run --target javascript):

10000000000000000

As of recently, Gleam compiler started to output a warning when dealing with big numbers in JS target:

warning: Int is outside JavaScript's safe integer range
  ┌─ /Users/adi.salimgereyev/hello_world/src/hello_world.gleam:5:14
  │
5 │   io.println(9_999_999_999_999_999 |> int.to_string)
  │              ^^^^^^^^^^^^^^^^^^^^^ This is not a safe integer value on JavaScript

This integer value is too large to be represented accurately by
JavaScript's number type. To avoid this warning integer values must be in
the range -(2^53 - 1) - (2^53 - 1).

See JavaScript's Number.MAX_SAFE_INTEGER and Number.MIN_SAFE_INTEGER
properties for more information.

I think the current cross-target inconsistency is a real foot-gun and we should prefer strict, portable semantics.

Proposal: be strict and make Int portable

Make Int compile to BigInt on the JS target (just like it's currently implemented in bigi), so Int means "mathematically exact integer" on both BEAM and JS. That gives us one mental model and identical results across backends.

Alongside strict Int, introduce a dedicated small-integer type that is guaranteed to fit in JS's safe range - call it something like SmallInt. On JS it maps to Number; on BEAM it maps to Int and enforces the same range at construction.

This gives users an explicit, performance-oriented choice for counters, indices, interop with JS APIs, etc., while keeping default Int exact and cross-target consistent. (On BEAM, small integers are already an optimized representation; this mirrors that idea semantically)

Do you think it's worth it?

[lpil]

This is by design. The limits of the number type is target dependant.

Make Int compile to BigInt on the JS target (just like it's currently implemented in bigi), so Int means "mathematically exact integer" on both BEAM and JS. That gives us one mental model and identical results across backends.

We did previously try this, but it performs too poorly to be a viable option.