CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-long

A Long class for representing a 64-bit two's-complement integer value.

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

Long.js

Long.js is a JavaScript library for representing 64-bit two's-complement integer values, addressing JavaScript's native number limitations (safe integers only up to 2^53-1). Derived from Google Closure Library with WebAssembly optimizations for high-performance 64-bit integer operations.

Package Information

  • Package Name: long
  • Package Type: npm
  • Language: JavaScript (with TypeScript definitions)
  • Installation: npm install long

Core Imports

import Long from "long";

For CommonJS:

const Long = require("long");

Basic Usage

import Long from "long";

// Create Long instances
const a = Long.fromString("9223372036854775807");
const b = Long.fromNumber(1000);
const c = new Long(0xFFFFFFFF, 0x7FFFFFFF); // low, high bits

// Perform operations
const sum = a.add(b);
const product = a.multiply(Long.fromInt(2));
const quotient = a.divide(b);

// Convert back to other formats
console.log(sum.toString());     // "9223372036854776807"
console.log(product.toNumber()); // May lose precision for large values
console.log(quotient.toBigInt()); // 9223372036854775n

Architecture

Long.js provides a complete 64-bit integer implementation with:

  • Immutable Operations: All operations return new Long instances
  • Type Safety: Full support for both signed and unsigned 64-bit integers
  • Multiple Input Formats: Create from strings, numbers, bytes, or bit values
  • WebAssembly Optimizations: Native i64 operations for multiplication and division
  • JavaScript Integration: Seamless conversion to native types including BigInt

Capabilities

Constructor and Constants

Create Long instances and access predefined constants.

/**
 * Constructs a 64-bit two's-complement integer
 * @param low - Lower 32 bits as signed integer
 * @param high - Upper 32 bits as signed integer  
 * @param unsigned - Whether this represents an unsigned value
 */
constructor(low: number, high: number, unsigned?: boolean);

// Predefined constants
static readonly ZERO: Long;           // Signed zero
static readonly UZERO: Long;          // Unsigned zero
static readonly ONE: Long;            // Signed one
static readonly UONE: Long;           // Unsigned one
static readonly NEG_ONE: Long;        // Signed negative one
static readonly MAX_VALUE: Long;      // Maximum signed value (2^63-1)
static readonly MIN_VALUE: Long;      // Minimum signed value (-2^63)
static readonly MAX_UNSIGNED_VALUE: Long;  // Maximum unsigned value (2^64-1)
static readonly MAX_SAFE_INTEGER: Long;    // Maximum safe JS integer (2^53-1)
static readonly MIN_SAFE_INTEGER: Long;    // Minimum safe JS integer (-2^53+1)

Static Creation Methods

Create Long instances from various input types.

/**
 * Creates a Long from a 32-bit integer
 */
static fromInt(value: number, unsigned?: boolean): Long;

/**
 * Creates a Long from a JavaScript number
 */
static fromNumber(value: number, unsigned?: boolean): Long;

/**
 * Creates a Long from a string representation
 */
static fromString(str: string, unsigned?: boolean, radix?: number): Long;

/**
 * Creates a Long from a byte array
 */
static fromBytes(bytes: number[], unsigned?: boolean, le?: boolean): Long;

/**
 * Creates a Long from low and high 32-bit values
 */
static fromBits(lowBits: number, highBits: number, unsigned?: boolean): Long;

/**
 * Creates a Long from various input types
 */
static fromValue(val: Long | number | string | {low: number, high: number, unsigned?: boolean}, unsigned?: boolean): Long;

/**
 * Creates a Long from a BigInt value
 */
static fromBigInt(value: bigint, unsigned?: boolean): Long;

/**
 * Tests if an object is a Long instance
 */
static isLong(obj: any): obj is Long;

Instance Properties

Access the internal representation of Long values.

/** Lower 32 bits as signed integer */
readonly low: number;

/** Upper 32 bits as signed integer */  
readonly high: number;

/** Whether this Long represents an unsigned value */
readonly unsigned: boolean;

Arithmetic Operations

Perform mathematical operations on Long values.

/**
 * Adds another Long to this Long
 */
add(addend: Long | number | string): Long;

/**
 * Subtracts another Long from this Long
 */
subtract(subtrahend: Long | number | string): Long;

/**
 * Multiplies this Long by another Long
 */
multiply(multiplier: Long | number | string): Long;

/**
 * Divides this Long by another Long
 */
divide(divisor: Long | number | string): Long;

/**
 * Gets the remainder of division by another Long
 */
modulo(divisor: Long | number | string): Long;

/**
 * Returns the negation of this Long
 */
negate(): Long;

/**
 * Returns the absolute value of this Long
 */
abs(): Long;

Bitwise Operations

Perform bitwise operations on Long values.

/**
 * Performs bitwise AND operation
 */
and(other: Long | number | string): Long;

/**
 * Performs bitwise OR operation
 */
or(other: Long | number | string): Long;

/**
 * Performs bitwise XOR operation
 */
xor(other: Long | number | string): Long;

/**
 * Performs bitwise NOT operation
 */
not(): Long;

/**
 * Shifts bits left by specified number of positions
 */
shiftLeft(numBits: number): Long;

/**
 * Performs arithmetic right shift (sign-extending)
 */
shiftRight(numBits: number): Long;

/**
 * Performs logical right shift (zero-filling)
 */
shiftRightUnsigned(numBits: number): Long;

/**
 * Rotates bits left by specified number of positions
 */
rotateLeft(numBits: number): Long;

/**
 * Rotates bits right by specified number of positions
 */
rotateRight(numBits: number): Long;

Comparison Operations

Compare Long values with each other.

/**
 * Tests if this Long equals another Long
 */
equals(other: Long | number | string): boolean;

/**
 * Tests if this Long does not equal another Long
 */
notEquals(other: Long | number | string): boolean;

/**
 * Tests if this Long is less than another Long
 */
lessThan(other: Long | number | string): boolean;

/**
 * Tests if this Long is less than or equal to another Long
 */
lessThanOrEqual(other: Long | number | string): boolean;

/**
 * Tests if this Long is greater than another Long
 */
greaterThan(other: Long | number | string): boolean;

/**
 * Tests if this Long is greater than or equal to another Long
 */
greaterThanOrEqual(other: Long | number | string): boolean;

/**
 * Compares this Long with another Long
 * @returns -1 if less than, 0 if equal, 1 if greater than
 */
compare(other: Long | number | string): number;

/**
 * Alias for compare method
 */
comp(other: Long | number | string): number;

Conversion Operations

Convert Long values to other formats.

/**
 * Converts to JavaScript number (may lose precision)
 */
toNumber(): number;

/**
 * Converts to native BigInt value
 */
toBigInt(): bigint;

/**
 * Converts to string representation
 */
toString(radix?: number): string;

/**
 * Converts to byte array
 */
toBytes(le?: boolean): number[];

/**
 * Converts to little-endian byte array
 */
toBytesLE(): number[];

/**
 * Converts to big-endian byte array
 */
toBytesBE(): number[];

/**
 * Returns numeric value (calls toNumber)
 */
valueOf(): number;

Type and State Checking

Check properties and state of Long values.

/**
 * Tests if this Long is zero
 */
isZero(): boolean;

/**
 * Tests if this Long is negative
 */
isNegative(): boolean;

/**
 * Tests if this Long is positive
 */
isPositive(): boolean;

/**
 * Tests if this Long is odd
 */
isOdd(): boolean;

/**
 * Tests if this Long is even
 */
isEven(): boolean;

/**
 * Tests if this Long is within safe JavaScript integer range
 */
isSafeInteger(): boolean;

Type Conversion

Convert between signed and unsigned representations.

/**
 * Converts to signed representation
 */
toSigned(): Long;

/**
 * Converts to unsigned representation
 */
toUnsigned(): Long;

Error Handling

Long.js throws errors in the following cases:

  • Division by zero: divide() and modulo() methods throw RangeError when divisor is zero
  • Invalid string parsing: fromString() throws Error for invalid string representations
  • Overflow conditions: Handled according to 64-bit two's complement arithmetic rules with wrapping

WebAssembly Integration

Long.js includes WebAssembly optimizations for enhanced performance:

  • Multiplication operations: Uses native i64 multiplication when available
  • Division operations: Uses native i64 division for both signed and unsigned operations
  • Remainder operations: Uses native i64 remainder calculation for optimal performance

Usage Examples

Working with large integers:

// Cryptocurrency calculations
const satoshis = Long.fromString("2100000000000000"); // Max Bitcoin supply in satoshis
const btcPrice = Long.fromNumber(50000);
const totalValue = satoshis.multiply(btcPrice);

// Database ID management
const userId = Long.fromString("18446744073709551615"); // Max uint64
const isValidId = userId.lessThan(Long.MAX_UNSIGNED_VALUE);

// Timestamp operations
const timestamp = Long.fromNumber(Date.now()).multiply(1000000); // Convert to nanoseconds
const futureTime = timestamp.add(Long.fromNumber(86400000000000)); // Add 1 day in nanoseconds

Bitwise operations for flags:

const FLAGS = {
  READ: Long.fromInt(1),    // 0001
  WRITE: Long.fromInt(2),   // 0010
  EXECUTE: Long.fromInt(4), // 0100
  ADMIN: Long.fromInt(8)    // 1000
};

let permissions = Long.ZERO;
permissions = permissions.or(FLAGS.READ).or(FLAGS.WRITE);

const canRead = permissions.and(FLAGS.READ).notEquals(Long.ZERO);
const canExecute = permissions.and(FLAGS.EXECUTE).notEquals(Long.ZERO);

docs

index.md

tile.json