René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"ffi: accept safe integer numbers for int64 and uint64 arguments","articleBody":"### What is the problem this feature will solve?\n\nCurrently, `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.\n\nThis 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:\n\n```c\nuint64_t sum_buffer(const uint8_t* buffer, uint64_t length);\n```\n\n```js\nconst { functions } = ffi.dlopen(libraryPath, {\n  sum_buffer: {\n    arguments: ['buffer', 'u64'],\n    return: 'u64',\n  },\n});\n\nconst bytes = new Uint8Array([1, 2, 3]);\n\nfunctions.sum_buffer(bytes, bytes.byteLength);         // ERR_INVALID_ARG_VALUE\nfunctions.sum_buffer(bytes, BigInt(bytes.byteLength)); // 6n\n```\n\n`bytes.byteLength` is 3, but the caller still needs to wrap it in `BigInt()` because the native parameter is declared as `uint64_t`.\n\nThe same issue applies to arguments unrelated to buffers, such as counters or offsets:\n\n```js\nconst { functions } = ffi.dlopen(libraryPath, {\n  set_counter: {\n    arguments: ['u64'],\n    return: 'void',\n  },\n});\n\nconst count = 100;\nfunctions.set_counter(count); // ERR_INVALID_ARG_VALUE\nfunctions.set_counter(BigInt(count)); // 100\n```\n\nRequiring 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.\n\n### What is the feature you are proposing to solve the problem?\n\nAllow safe integer numbers as `int64` and `uint64` FFI arguments, alongside the existing bigint support.\n\nThe accepted number ranges would be:\n\n- int64 / i64: `Number.MIN_SAFE_INTEGER` through `Number.MAX_SAFE_INTEGER`.\n- uint64 / u64: 0 through `Number.MAX_SAFE_INTEGER`.\n\nNode.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`.\n\n```js\nfunctions.sum_buffer(bytes, bytes.byteLength);\nfunctions.set_counter(100);\n```\nExisting bigint arguments would continue to work, including values beyond the safe integer range that fit within the declared native type:\n\n```js\nfunctions.set_counter(100);                         // Accepted\nfunctions.set_counter(100n);                        // Still accepted\nfunctions.set_counter((2n ** 64n) - 1n);             // Still accepted\n\nfunctions.set_counter(-1);                          // Rejected\nfunctions.set_counter(1.5);                         // Rejected\nfunctions.set_counter(Number.MAX_SAFE_INTEGER + 1); // Rejected\nfunctions.set_counter(2n ** 64n);                    // Rejected\n```\n\nThe 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.\n\nThis 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.\n\nI'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.\n\n### What alternatives have you considered?\n\nI 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.\n\nBoth 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.\n\nAccepting safe integer numbers would remove that extra step for common calls while retaining explicit range checks and bigint support for larger values.","author":{"url":"https://github.com/HoonDongKang","@type":"Person","name":"HoonDongKang"},"datePublished":"2026-09-22T09:20:37Z","url":"https://github.com/nodejs/node/issues/66198"}