ffi: accept safe integer numbers for int64 and uint64 arguments

[HoonDongKang]

What is the problem this feature will solve?

Currently, int64 and uint64 FFI arguments require JavaScript bigint values. Passing a number is rejected even when it is a small integer that can be represented exactly by both JavaScript and the native type.

This adds an explicit conversion at the call site when the value is already available as a number. A common example is passing a buffer and its length to a native function:

uint64_t sum_buffer(const uint8_t* buffer, uint64_t length);

const { functions } = ffi.dlopen(libraryPath, {
  sum_buffer: {
    arguments: ['buffer', 'u64'],
    return: 'u64',
  },
});

const bytes = new Uint8Array([1, 2, 3]);

functions.sum_buffer(bytes, bytes.byteLength);         // ERR_INVALID_ARG_VALUE
functions.sum_buffer(bytes, BigInt(bytes.byteLength)); // 6n

bytes.byteLength is 3, but the caller still needs to wrap it in BigInt() because the native parameter is declared as uint64_t.

The same issue applies to arguments unrelated to buffers, such as counters or offsets:

const { functions } = ffi.dlopen(libraryPath, {
  set_counter: {
    arguments: ['u64'],
    return: 'void',
  },
});

const count = 100;
functions.set_count(count); // ERR_INVALID_ARG_VALUE
functions.set_counter(BigInt(count)); // 100

Requiring bigint makes sense when a value is outside JavaScript's safe integer range. For values already within that range, however, it seems useful to let the runtime validate and convert them rather than requiring callers to do so explicitly.

What is the feature you are proposing to solve the problem?

Allow safe integer numbers as int64 and uint64 FFI arguments, alongside the existing bigint support.

The accepted number ranges would be:

• int64 / i64: Number.MIN_SAFE_INTEGER through Number.MAX_SAFE_INTEGER.
• uint64 / u64: 0 through Number.MAX_SAFE_INTEGER.

Node.js would validate the number before converting it internally. Fractional numbers, NaN, infinities, and numbers outside the accepted range would throw ERR_INVALID_ARG_VALUE. Negative numbers would also be rejected for uint64.

functions.sum_buffer(bytes, bytes.byteLength);
functions.set_counter(100);

Existing bigint arguments would continue to work, including values beyond the safe integer range that fit within the declared native type:

functions.set_counter(100);                         // Accepted
functions.set_counter(100n);                        // Still accepted
functions.set_counter((2n ** 64n) - 1n);             // Still accepted

functions.set_counter(-1);                          // Rejected
functions.set_counter(1.5);                         // Rejected
functions.set_counter(Number.MAX_SAFE_INTEGER + 1); // Rejected
functions.set_counter(2n ** 64n);                    // Rejected

The number restriction is intentional: converting an unsafe number to bigint cannot recover precision that may already have been lost. Callers would still need bigint for integers outside the safe integer range.

This proposal only changes which values are accepted as native function arguments. It does not change 64-bit return values, which would remain bigint, or infer a buffer length automatically.

I've opened a related PR #66197 with the implementation, documentation, and tests covering the Fast API, SharedBuffer, and generic argument conversion paths. A review of the proposed behavior and implementation would be appreciated.

What alternatives have you considered?

I haven't identified another approach that addresses this without changing the accepted argument types. Callers can continue using BigInt() explicitly, or put those conversions in their own wrapper functions.

Both approaches work, but callers still need to handle the conversion whenever an existing number is passed to an int64 or uint64 parameter. For example, passing buffer.byteLength requires an extra BigInt() call even though the length is already a suitable integer.

Accepting safe integer numbers would remove that extra step for common calls while retaining explicit range checks and bigint support for larger values.