@xtuc/long 4.2.2: fromString

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify 64-bit integer arithmetic and string parsing with Long.fromString in pkg:npm/%40xtuc/long@4.2.2
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40xtuc/long@4.2.2
Demonstrate these symbols/APIs:
  - @xtuc/long.fromString

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:f8f180e10e1b8ac28a718a4749333553cebd2e827521b84e018d3a3b313bd75d","contract":["Long and utility functions are exported correctly","Long.fromString parses signed 64-bit integer strings including boundary values","Long.fromString parses unsigned 64-bit integer strings with custom radix support","add64 and multiply64 perform precise 64-bit arithmetic beyond Number.MAX_SAFE_INTEGER","divide64 computes 64-bit division and compare64 evaluates relational ordering","bitwiseAnd64 and shiftLeft64 perform exact 64-bit bitwise logic and shifting"],"goal":"verify 64-bit integer arithmetic and string parsing with Long.fromString in pkg:npm/%40xtuc/long@4.2.2","kind":"HOW","packages":["pkg:npm/%40xtuc/long@4.2.2"],"schemaVersion":1,"symbols":["@xtuc/long.fromString"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/%40xtuc/long@4.2.2"],"schemaVersion":1,"subject":"pkg:npm/%40xtuc/long@4.2.2","symbols":["@xtuc/long.fromString"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-xtuc-long",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-xtuc-long",
      "version": "1.0.0",
      "dependencies": {
        "@xtuc/long": "4.2.2"
      }
    },
    "node_modules/@xtuc/long": {
      "version": "4.2.2",
      "resolved": "https://registry.npmjs.org/@xtuc/long/-/long-4.2.2.tgz",
      "integrity": "sha512-NuHqBY1PB/D8xU6s/thBgOAiAP7HOYDQ32+BFZILJ8ivkUkAHQnWfn6WhL79Owj1qmUnoN/YPhktdIoucipkAQ==",
      "license": "Apache-2.0"
    }
  }
}

{
  "name": "sample-xtuc-long",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification of @xtuc/long",
  "main": "src/index.js",
  "dependencies": {
    "@xtuc/long": "4.2.2"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify 64-bit integer arithmetic and string parsing with Long.fromString in pkg:npm/%40xtuc/long@4.2.2",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40xtuc/long@4.2.2"
  ],
  "symbols": [
    "@xtuc/long.fromString"
  ]
}

const LongModule = require('@xtuc/long');
const Long = typeof LongModule === 'function' ? LongModule : LongModule.default;

/**
 * Parse a 64-bit integer from a string with specified signedness and radix.
 * @param {string} str - String representation of the 64-bit integer.
 * @param {boolean} [unsigned=false] - Whether the number is unsigned.
 * @param {number} [radix=10] - Radix between 2 and 36.
 * @returns {import('@xtuc/long')} Long instance.
 */
function parse64BitInt(str, unsigned = false, radix = 10) {
  return Long.fromString(str, unsigned, radix);
}

/**
 * Add two 64-bit integers given as strings and return the decimal string result.
 * @param {string} aStr
 * @param {string} bStr
 * @param {boolean} [unsigned=false]
 * @returns {string}
 */
function add64(aStr, bStr, unsigned = false) {
  const a = Long.fromString(aStr, unsigned);
  const b = Long.fromString(bStr, unsigned);
  return a.add(b).toString();
}

/**
 * Multiply two 64-bit integers given as strings and return the decimal string result.
 * @param {string} aStr
 * @param {string} bStr
 * @param {boolean} [unsigned=false]
 * @returns {string}
 */
function multiply64(aStr, bStr, unsigned = false) {
  const a = Long.fromString(aStr, unsigned);
  const b = Long.fromString(bStr, unsigned);
  return a.multiply(b).toString();
}

/**
 * Divide two 64-bit integers given as strings and return the decimal string quotient.
 * @param {string} aStr
 * @param {string} bStr
 * @param {boolean} [unsigned=false]
 * @returns {string}
 */
function divide64(aStr, bStr, unsigned = false) {
  const a = Long.fromString(aStr, unsigned);
  const b = Long.fromString(bStr, unsigned);
  return a.divide(b).toString();
}

/**
 * Perform bitwise AND between two 64-bit integer strings.
 * @param {string} aStr
 * @param {string} bStr
 * @param {boolean} [unsigned=false]
 * @returns {string}
 */
function bitwiseAnd64(aStr, bStr, unsigned = false) {
  const a = Long.fromString(aStr, unsigned);
  const b = Long.fromString(bStr, unsigned);
  return a.and(b).toString();
}

/**
 * Shift a 64-bit integer left by the specified bit count.
 * @param {string} valStr
 * @param {number} numBits
 * @param {boolean} [unsigned=false]
 * @returns {string}
 */
function shiftLeft64(valStr, numBits, unsigned = false) {
  const val = Long.fromString(valStr, unsigned);
  return val.shiftLeft(numBits).toString();
}

/**
 * Compare two 64-bit integers represented by strings.
 * Returns -1 if a < b, 0 if a == b, 1 if a > b.
 * @param {string} aStr
 * @param {string} bStr
 * @param {boolean} [unsigned=false]
 * @returns {number}
 */
function compare64(aStr, bStr, unsigned = false) {
  const a = Long.fromString(aStr, unsigned);
  const b = Long.fromString(bStr, unsigned);
  return a.compare(b);
}

/**
 * Convert a 64-bit integer string into its hexadecimal string representation.
 * @param {string} str
 * @param {boolean} [unsigned=true]
 * @returns {string}
 */
function toHexString64(str, unsigned = true) {
  const val = Long.fromString(str, unsigned, 10);
  return val.toString(16);
}

module.exports = {
  Long,
  parse64BitInt,
  add64,
  multiply64,
  divide64,
  bitwiseAnd64,
  shiftLeft64,
  compare64,
  toHexString64
};

import assert from 'node:assert';
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const {
  Long,
  parse64BitInt,
  add64,
  multiply64,
  divide64,
  bitwiseAnd64,
  shiftLeft64,
  compare64,
  toHexString64
} = require('../src/index.js');

// 1. Export verification
assert.strictEqual(typeof Long, 'function', 'Long should be exported as a constructor function');
assert.strictEqual(typeof parse64BitInt, 'function', 'parse64BitInt should be exported as a function');
assert.strictEqual(typeof add64, 'function', 'add64 should be exported as a function');
assert.strictEqual(typeof multiply64, 'function', 'multiply64 should be exported as a function');
assert.strictEqual(typeof divide64, 'function', 'divide64 should be exported as a function');
assert.strictEqual(typeof bitwiseAnd64, 'function', 'bitwiseAnd64 should be exported as a function');
assert.strictEqual(typeof shiftLeft64, 'function', 'shiftLeft64 should be exported as a function');
assert.strictEqual(typeof compare64, 'function', 'compare64 should be exported as a function');
assert.strictEqual(typeof toHexString64, 'function', 'toHexString64 should be exported as a function');

// 2. Long.fromString parses signed 64-bit integer strings including boundary values
const maxSigned = Long.fromString('9223372036854775807');
assert.strictEqual(maxSigned.toString(), '9223372036854775807', 'Max signed 64-bit value should match');
assert.strictEqual(maxSigned.getHighBits(), 2147483647, 'High bits of MAX_VALUE should match');
assert.strictEqual(maxSigned.getLowBits(), -1, 'Low bits of MAX_VALUE should match');

const minSigned = Long.fromString('-9223372036854775808');
assert.strictEqual(minSigned.toString(), '-9223372036854775808', 'Min signed 64-bit value should match');
assert.strictEqual(minSigned.isNegative(), true, 'Min signed value should be negative');

const zero = parse64BitInt('0');
assert.strictEqual(zero.isZero(), true, 'Zero should evaluate to isZero');

// 3. Long.fromString parses unsigned 64-bit integer strings with custom radix support
const maxUnsigned = parse64BitInt('18446744073709551615', true);
assert.strictEqual(maxUnsigned.toString(), '18446744073709551615', 'Max unsigned 64-bit value should match');
assert.strictEqual(maxUnsigned.unsigned, true, 'Unsigned flag should be true');

const hexParsed = parse64BitInt('deadbeefcafe', true, 16);
assert.strictEqual(hexParsed.toString(16), 'deadbeefcafe', 'Hex parsing and formatting should match');

const binParsed = parse64BitInt('110101', false, 2);
assert.strictEqual(binParsed.toInt(), 53, 'Binary parsing should equal 53');

// 4. add64 and multiply64 perform precise 64-bit arithmetic beyond Number.MAX_SAFE_INTEGER
const sumResult = add64('9007199254740992', '1000');
assert.strictEqual(sumResult, '9007199254741992', 'Addition beyond MAX_SAFE_INTEGER should be exact');

const mulResult = multiply64('1000000000', '1000000000');
assert.strictEqual(mulResult, '1000000000000000000', 'Multiplication 10^9 * 10^9 should be 10^18');

// 5. divide64 computes 64-bit division and compare64 evaluates relational ordering
const divResult = divide64('1000000000000000000', '1000000000');
assert.strictEqual(divResult, '1000000000', 'Division 10^18 / 10^9 should be 10^9');

assert.strictEqual(compare64('500', '1000'), -1, '500 < 1000 should return -1');
assert.strictEqual(compare64('1000', '1000'), 0, '1000 == 1000 should return 0');
assert.strictEqual(compare64('2000', '1000'), 1, '2000 > 1000 should return 1');

// 6. bitwiseAnd64 and shiftLeft64 perform exact 64-bit bitwise logic and shifting
const andResult = bitwiseAnd64('255', '15');
assert.strictEqual(andResult, '15', '255 & 15 should equal 15');

const shiftResult = shiftLeft64('1', 40);
assert.strictEqual(shiftResult, '1099511627776', '1 << 40 should equal 1099511627776 (1 TiB)');

const hexStr = toHexString64('1099511627776', true);
assert.strictEqual(hexStr, '10000000000', 'Hex string of 2^40 should be 10000000000');

console.log('Contract tests passed successfully.');