64-bit Integer Representation for JavaScript

Common errors

• ReferenceError: require is not defined

  cause Attempting to use `require()` in an ES module context or a browser environment without a bundler that polyfills `require`.
  fix This package is CommonJS-only. Ensure your Node.js project is configured for CommonJS (e.g., without `"type": "module"` in `package.json` or by using a bundler). For browser environments, a bundler is necessary.

• TypeError: Int64 is not a constructor

  cause The `Int64` symbol was not correctly imported or assigned, or the package failed to load.
  fix Verify that `const Int64 = require('node-int64');` is correctly placed and executed before `new Int64(...)` calls. Check `node_modules` for `node-int64`.

• ReferenceError: Buffer is not defined

  cause Attempting to use `Buffer` in a browser environment without a polyfill, or in an older Node.js context where `Buffer` might not be globally available if not explicitly required/imported (less common in modern Node.js).
  fix For browser usage, a polyfill for Node.js `Buffer` is required. In Node.js, `Buffer` is typically global, but if not, ensure `const Buffer = require('buffer').Buffer;` or similar is used.

Warnings

• breaking The `new Buffer()` constructor used in older examples and package internals is deprecated and can pose security risks. It has been replaced by `Buffer.from()`, `Buffer.alloc()`, and `Buffer.allocUnsafe()`.
  Fix: While `node-int64` itself uses `new Buffer()` internally, direct usage in consuming code should be updated. For creating Int64 from a buffer, use `new Int64(Buffer.from([...]))` or `new Int64(new Uint8Array([...]))`.
• gotcha This library is designed for *representing* 64-bit integers, not for performing 64-bit *arithmetic*. Operations like addition or subtraction on `Int64` instances will implicitly convert them to standard JavaScript numbers, leading to precision loss if the value exceeds 2^53.
  Fix: If 64-bit arithmetic is required, consider using native `BigInt` (available in Node.js v10.5.0+ and modern browsers) or a different arbitrary-precision arithmetic library like `js-big-decimal`.
• deprecated The `node-int64` package is not actively maintained, and its author suggests it will be obsoleted by the native `BigInt` feature in JavaScript. Users are encouraged to migrate to `BigInt` for 64-bit integer handling when feasible.
  Fix: Evaluate migrating to native JavaScript `BigInt`. For example, `new Int64('...')` can often be replaced with `BigInt('0x...')` or `BigInt('...')`.
• gotcha When an `Int64` instance represents a value outside the safe integer range of JavaScript numbers (i.e., beyond +/- 2^53), attempting to coerce it to a number (e.g., through `valueOf()`, `+` operator, or implicit conversion) will result in `Infinity` or `NaN`, despite the internal 64-bit representation being accurate.
  Fix: Always use methods like `toOctetString()` or `toBuffer()` to retrieve the full 64-bit precision, or `toString(radix)` for string representation, rather than relying on numerical coercion, especially for large values.

Install

• npm install node-int64 npm
• yarn add node-int64 yarn
• pnpm add node-int64 pnpm

Imports

• Int64
  wrong:

  import Int64 from 'node-int64'; // This package is CommonJS-only.
  import { Int64 } from 'node-int64'; // This package is CommonJS-only.

  correct:

  const Int64 = require('node-int64');

  The `node-int64` package is a CommonJS module and does not support ESM imports. It exports the `Int64` class directly as `module.exports`.
• new Int64(value)

  const myInt = new Int64('123456789abcdef0');

  The constructor accepts numbers, hex strings, two 32-bit words, or Buffer/Uint8Array instances.
• Int64 (TypeScript type)
  wrong:

  import { Int64 } from 'node-int64'; // The community-maintained types use 'export = Int64'.

  correct:

  import Int64 = require('node-int64');
  // or
  /// <reference types="node-int64" />

  For TypeScript, the community-maintained `@types/node-int64` package should be installed. It uses `export = Int64`, requiring a `require` style import for types.

Quickstart

Demonstrates creating `Int64` instances from various inputs (number, hex string, Buffer) and basic output operations like `toOctetString` and `toBuffer`.

const Int64 = require('node-int64');

// Create an Int64 from a JavaScript number (up to 2^53 precision)
const smallInt = new Int64(0x123456789);
console.log(`Small Int: ${smallInt.toString(16)} (value: ${smallInt.valueOf()})`);

// Create an Int64 from a hexadecimal string for full 64-bit precision
const bigHex = '123456789abcdef0';
const largeInt = new Int64(bigHex);
console.log(`Large Int (hex): ${largeInt.toOctetString()} (value: ${largeInt.valueOf()})`);

// Create an Int64 from a Node.js Buffer
const buffer = Buffer.from([0xDE, 0xAD, 0xBE, 0xEF, 0x01, 0x02, 0x03, 0x04]);
const intFromBuffer = new Int64(buffer);
console.log(`From Buffer: ${intFromBuffer.toOctetString()} (value: ${intFromBuffer.valueOf()})`);

// Extract the 64-bit value into a Buffer
const outputBuffer = intFromBuffer.toBuffer();
console.log(`To Buffer: ${outputBuffer.toString('hex')}`);

// Check if the internal value is within JS safe integer range
console.log(`Is smallInt finite (JS precision): ${isFinite(smallInt)}`);
console.log(`Is largeInt finite (JS precision): ${isFinite(largeInt)}`);