{"id":11091,"library":"int64-buffer","title":"int64-buffer 64-bit Integer Library","description":"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.","status":"active","version":"1.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/kawanet/int64-buffer","tags":["javascript","64bit","IEEE-754","arraybuffer","buffer","int","int64","int8array","integer","typescript"],"install":[{"cmd":"npm install int64-buffer","lang":"bash","label":"npm"},{"cmd":"yarn add int64-buffer","lang":"bash","label":"yarn"},{"cmd":"pnpm add int64-buffer","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primary import for signed 64-bit integers with big-endian storage.","wrong":"const Int64BE = require('int64-buffer').Int64BE;","symbol":"Int64BE","correct":"import { Int64BE } from 'int64-buffer';"},{"note":"Used for unsigned 64-bit integers with big-endian storage; often mistaken as the default export.","wrong":"const Uint64BE = require('int64-buffer');","symbol":"Uint64BE","correct":"import { Uint64BE } from 'int64-buffer';"},{"note":"For signed 64-bit integers with little-endian storage. All classes are named exports.","wrong":"import * as Int64LE from 'int64-buffer';","symbol":"Int64LE","correct":"import { Int64LE } from 'int64-buffer';"}],"quickstart":{"code":"import { Int64BE, Uint64BE, Uint64LE } from 'int64-buffer';\n\n// Working with a signed 64-bit integer (Big Endian)\nconst signedBig = new Int64BE(-1);\nconsole.log(`Signed Int64BE: ${signedBig.toString(10)}`);\nconsole.log(`Buffer representation: ${signedBig.toBuffer().toString('hex')}`);\n\n// Working with an unsigned 64-bit integer from high/low 32-bit parts (Big Endian)\nconst unsignedBig = new Uint64BE(0x12345678, 0x9abcdef0);\nconsole.log(`Unsigned Uint64BE (hex): ${unsignedBig.toString(16)}`);\nconsole.log(`Unsigned Uint64BE (decimal string): ${unsignedBig.toString(10)}`);\n\n// Demonstrating precision loss when coercing to standard JavaScript Number\nconst largeNumberJs = Math.pow(2, 63); // JavaScript Number, often loses precision\nconst largeUint64BE = new Uint64BE('9223372036854775808', 10); // Constructing from string for accuracy\nconsole.log(`JS number (potential precision loss): ${largeNumberJs}`);\nconsole.log(`Uint64BE (correct value): ${largeUint64BE.toString(10)}`);\n\n// Creating from a byte array (Little Endian example)\nconst littleEndianBytes = new Uint8Array([0xF0, 0xDE, 0xBC, 0x9A, 0x78, 0x56, 0x34, 0x12]);\nconst littleEndianBig = new Uint64LE(littleEndianBytes);\nconsole.log(`Uint64LE from bytes (hex): ${littleEndianBig.toString(16)}`);\n\n// Example of writing a value into an existing buffer at an offset\nconst targetBuffer = Buffer.alloc(16); // Requires Node.js Buffer or a polyfill\nconst valueToWrite = new Uint64BE(0xCAFEBABE, 0xDEDDECAF);\nnew Uint64BE(targetBuffer, 8, valueToWrite.high, valueToWrite.low); // Write into buffer at offset 8\nconsole.log(`Buffer with written value at offset 8: ${targetBuffer.toString('hex')}`);","lang":"typescript","description":"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."},"warnings":[{"fix":"For arithmetic operations, consider libraries like 'js-big-decimal' or 'big-integer', or implement logic using high/low 32-bit components.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to perform arithmetic operations (e.g., add, subtract) directly on an `int64-buffer` instance, which the library does not support.","error":"TypeError: big.add is not a function"},{"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.","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).","error":"Value displayed as 9223372036854776000 instead of 9223372036854775808"},{"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.","cause":"Attempting to use `Buffer.from(...)` or `Buffer.alloc(...)` directly in a browser environment without a Node.js `Buffer` polyfill.","error":"ReferenceError: Buffer is not defined"}],"ecosystem":"npm"}