int64-buffer 64-bit Integer Library

Common errors

• TypeError: big.add is not a function

  cause Attempting to perform arithmetic operations (e.g., add, subtract) directly on an `int64-buffer` instance, which the library does not support.
  fix This library is for storage and conversion only, not arithmetic. Use `toString()` to get the value and perform arithmetic with a dedicated bignum library, or implement manual operations on the high/low parts.

• Value displayed as 9223372036854776000 instead of 9223372036854775808

  cause The 64-bit integer was implicitly or explicitly converted to a standard JavaScript `number`, losing precision for values above `Number.MAX_SAFE_INTEGER` (2^53 - 1).
  fix Always use the `toString()` method (e.g., `big.toString(10)`) when you need to retrieve or display the full 64-bit value to maintain accuracy.

• ReferenceError: Buffer is not defined

  cause Attempting to use `Buffer.from(...)` or `Buffer.alloc(...)` directly in a browser environment without a Node.js `Buffer` polyfill.
  fix In browser environments, prefer `Uint8Array` or `Array` for byte array inputs/outputs. If `Buffer` functionality is required, ensure a compatible polyfill is included in your project.

Warnings

• gotcha This library deliberately does not provide mathematical operations (e.g., add, subtract, multiply, divide) for 64-bit integers. Users requiring arithmetic operations must implement them manually or use a different 'bignum' library.
  Fix: For arithmetic operations, consider libraries like 'js-big-decimal' or 'big-integer', or implement logic using high/low 32-bit components.
• gotcha Direct coercion of `int64-buffer` instances to JavaScript's standard `number` type (e.g., `big - 0`) will result in loss of precision for values exceeding `Number.MAX_SAFE_INTEGER` (2^53 - 1). The internal 64-bit precision will be lost.
  Fix: Always use `toString()` to obtain the full 64-bit value as a string for display or further processing to avoid precision loss. Avoid implicit or explicit casting to `number` for large values.
• gotcha When initializing `Uint64BE` or `Int64BE` with a JavaScript `number` that already exceeds 53 bits of precision, the input `number` itself might already be corrupted, leading to incorrect 64-bit values even before the library processes it.
  Fix: For values larger than `Number.MAX_SAFE_INTEGER`, initialize 64-bit integers from a string representation (e.g., `new Uint64BE('9223372036854775808', 10)`), or from explicit high and low 32-bit components, to guarantee accuracy.
• gotcha The library internally uses `Buffer` on Node.js and `Uint8Array` in web browsers for storage. While this is handled transparently for most operations, advanced scenarios involving direct buffer manipulation or specific environment dependencies might require awareness of the underlying type.
  Fix: If interacting directly with `toBuffer()` or providing a `Buffer` instance in a browser environment without a polyfill, `Buffer` might be undefined. Prefer `Uint8Array` or `ArrayBuffer` for universal compatibility or ensure a `Buffer` polyfill is present.

Install

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

Imports

• Int64BE
  wrong:

  const Int64BE = require('int64-buffer').Int64BE;

  correct:

  import { Int64BE } from 'int64-buffer';

  Primary import for signed 64-bit integers with big-endian storage.
• Uint64BE
  wrong:

  const Uint64BE = require('int64-buffer');

  correct:

  import { Uint64BE } from 'int64-buffer';

  Used for unsigned 64-bit integers with big-endian storage; often mistaken as the default export.
• Int64LE
  wrong:

  import * as Int64LE from 'int64-buffer';

  correct:

  import { Int64LE } from 'int64-buffer';

  For signed 64-bit integers with little-endian storage. All classes are named exports.

Quickstart

Demonstrates instantiation of signed and unsigned 64-bit integers in both big-endian and little-endian formats, shows conversions, highlights JavaScript number precision limits, and illustrates writing a value into an existing buffer at an offset.

import { Int64BE, Uint64BE, Uint64LE } from 'int64-buffer';

// Working with a signed 64-bit integer (Big Endian)
const signedBig = new Int64BE(-1);
console.log(`Signed Int64BE: ${signedBig.toString(10)}`);
console.log(`Buffer representation: ${signedBig.toBuffer().toString('hex')}`);

// Working with an unsigned 64-bit integer from high/low 32-bit parts (Big Endian)
const unsignedBig = new Uint64BE(0x12345678, 0x9abcdef0);
console.log(`Unsigned Uint64BE (hex): ${unsignedBig.toString(16)}`);
console.log(`Unsigned Uint64BE (decimal string): ${unsignedBig.toString(10)}`);

// Demonstrating precision loss when coercing to standard JavaScript Number
const largeNumberJs = Math.pow(2, 63); // JavaScript Number, often loses precision
const largeUint64BE = new Uint64BE('9223372036854775808', 10); // Constructing from string for accuracy
console.log(`JS number (potential precision loss): ${largeNumberJs}`);
console.log(`Uint64BE (correct value): ${largeUint64BE.toString(10)}`);

// Creating from a byte array (Little Endian example)
const littleEndianBytes = new Uint8Array([0xF0, 0xDE, 0xBC, 0x9A, 0x78, 0x56, 0x34, 0x12]);
const littleEndianBig = new Uint64LE(littleEndianBytes);
console.log(`Uint64LE from bytes (hex): ${littleEndianBig.toString(16)}`);

// Example of writing a value into an existing buffer at an offset
const targetBuffer = Buffer.alloc(16); // Requires Node.js Buffer or a polyfill
const valueToWrite = new Uint64BE(0xCAFEBABE, 0xDEDDECAF);
new Uint64BE(targetBuffer, 8, valueToWrite.high, valueToWrite.low); // Write into buffer at offset 8
console.log(`Buffer with written value at offset 8: ${targetBuffer.toString('hex')}`);