int64-buffer

library1.1.0jsnpmunverified

int64-buffer is a pure JavaScript library providing classes for reliable manipulation of 64-bit signed and unsigned integers (Int64BE, Uint64BE, Int64LE, Uint64LE). Unlike standard JavaScript numbers, which are IEEE-754 double-precision floats limited to 53 bits of integer precision, this package ensures full 64-bit accuracy. Currently at version 1.1.0, the library appears stable with infrequent but targeted updates, and has no notable release cadence. It stands out by explicitly *not* offering mathematical operations like addition or multiplication; instead, it focuses solely on efficient storage and conversion of 64-bit integers on `Buffer`, `Uint8Array`, or raw `Array` storage. It supports both big-endian (BE) and little-endian (LE) representations and operates without external dependencies, making it a lightweight (3KB minified) and portable solution for scenarios requiring precise 64-bit integer handling, such as parsing binary data streams or network protocols.

serialization data

npm install int64-buffer

github ↗package ↗

INSTALL

IMPORT

SIG · INT64-BUFFER

int64-buffer

serializationjavascriptv1.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Int64BE

✓ import { Int64BE } from 'int64-buffer';

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

Primary import for signed 64-bit integers with big-endian storage.

Uint64BE

✓ import { Uint64BE } from 'int64-buffer';

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

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

Int64LE

✓ import { Int64LE } from 'int64-buffer';

✗ import * as Int64LE from 'int64-buffer';

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

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')}`);

Debug

Known issues

gotchaThis 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.

affects: >=1.0.0

gotchaDirect 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.

affects: >=1.0.0

gotchaWhen 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.

affects: >=1.0.0

gotchaThe 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.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: big.add is not a function

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

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

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.

Upgrade

Version history

1.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

Bingbot

Resources

githubhttps://github.com/kawanet/int64-buffer ↗

packagehttps://www.npmjs.com/package/int64-buffer ↗