C-like Unsigned Integers

Common errors

• ReferenceError: UINT32 is not defined

  cause Attempting to use `UINT32` in Node.js without `require('cuint')` or in a browser without including the build script.
  fix In Node.js: `const { UINT32 } = require('cuint');`. In browser: ensure `<script src='/path/to/uint32.js'></script>` is present and loaded before usage.

• TypeError: Cannot read properties of undefined (reading 'add')

  cause Trying to call a method like `.add()` on a variable that is not an instance of `UINT32` or `UINT64`, possibly due to incorrect instantiation or a lost `this` context.
  fix Ensure the variable is correctly instantiated with `UINT32(...)` or `UINT64(...)` and that method calls are chained correctly or called on valid instances.

• SyntaxError: Named export 'UINT32' not found. The requested module 'cuint' does not provide an export named 'UINT32'

  cause Attempting to use ES Module `import { UINT32 } from 'cuint';` syntax with an abandoned CommonJS-only package in an ESM context.
  fix Use CommonJS `require()` syntax: `const { UINT32 } = require('cuint');`.

• TypeError: UINT32 is not a constructor

  cause Trying to use `new UINT32(...)` instead of `UINT32(...)` as the library's functions are factory functions, not traditional constructors.
  fix Call `UINT32()` or `UINT64()` directly without the `new` keyword, e.g., `const value = UINT32(123);`.

Warnings

• breaking Methods modify the object in place, requiring explicit `.clone()` for immutable operations. This behavior is C-like but non-idiomatic for typical JavaScript object operations.
  Fix: Always call `.clone()` on the original object before performing operations if you need to preserve the original value, e.g., `z = x.clone().add(y)`.
• gotcha The library is abandoned and has not been updated in over 9 years. This means it may have compatibility issues with newer Node.js versions, JavaScript engines, or security vulnerabilities that will not be patched.
  Fix: Consider using JavaScript's native `BigInt` for arbitrary precision integers or a more actively maintained library for fixed-width integer arithmetic if modern environments and security are concerns.
• gotcha Overflows are handled by C-like truncation to the respective 32-bit or 64-bit limit. This differs significantly from JavaScript's standard number behavior or `BigInt`'s arbitrary precision, which might lead to unexpected results if not accounted for.
  Fix: Be aware of the truncation behavior. Implement explicit checks if specific overflow handling (e.g., throwing an error) is required, rather than relying solely on the library's default behavior.
• gotcha The package does not provide native ES Module (ESM) exports. Direct `import ... from 'cuint'` syntax will not work in ESM-only Node.js environments or modern browser module contexts without a transpilation step.
  Fix: In CommonJS environments, use `const { UINT32 } = require('cuint');`. In ESM, you may need dynamic `import()` or to configure your build system to handle CJS modules, or use a tool like `esm` for Node.js.

Install

• npm install cuint npm
• yarn add cuint yarn
• pnpm add cuint pnpm

Imports

• UINT32
  wrong:

  import { UINT32 } from 'cuint';

  correct:

  const { UINT32 } = require('cuint');

  Primarily designed for CommonJS. For browser usage, include `uint32.js` via a `<script>` tag to expose `UINT32` globally. Native ESM import syntax is not supported and will likely result in an error or require a transpilation step.
• UINT64
  wrong:

  import { UINT64 } from 'cuint';

  correct:

  const { UINT64 } = require('cuint');

  Similar to `UINT32`, `UINT64` is exposed via CommonJS `require()` or globally in the browser when `uint64.js` (or a combined build) is included.
• UINT32 (Browser Global)
  wrong:

  import { UINT32 } from 'cuint/build/uint32.js';

  correct:

  // After including <script src="/your/path/to/uint32.js"></script>
  const val = UINT32('326648991');

  When used in a browser environment by including the build script, `UINT32` is directly available as a global variable. No explicit import or `require` is needed in this context.

Quickstart

Demonstrates importing `UINT32` and `UINT64` in Node.js, instantiating unsigned integer objects, performing in-place addition, and showcasing the `clone()` method for immutable operations, highlighting the library's C-like behavior with fixed-width arithmetic.

// In Node.js environment
const { UINT32, UINT64 } = require('cuint');

// Instantiate a 32-bit unsigned integer
const thirtyTwoBitValue = UINT32('4294967290'); // Close to max 32-bit unsigned value
console.log(`Initial UINT32 value: ${thirtyTwoBitValue.toString()}`);

// Instantiate another 32-bit value
const smallThirtyTwoBitValue = UINT32(10);

// Perform an addition (modifies thirtyTwoBitValue in place)
thirtyTwoBitValue.add(smallThirtyTwoBitValue);
console.log(`UINT32 after adding 10: ${thirtyTwoBitValue.toString()}`); // Will demonstrate truncation if it overflows

// Instantiate a 64-bit unsigned integer
const sixtyFourBitValue = UINT64('18446744073709551600'); // Close to max 64-bit unsigned value
console.log(`Initial UINT64 value: ${sixtyFourBitValue.toString()}`);

// Instantiate another 64-bit value
const smallSixtyFourBitValue = UINT64(15);

// Perform an addition (modifies sixtyFourBitValue in place)
sixtyFourBitValue.add(smallSixtyFourBitValue);
console.log(`UINT64 after adding 15: ${sixtyFourBitValue.toString()}`);

// Demonstrate cloning for immutable operations
const originalValue = UINT32(100);
const addedValue = UINT32(50);
const resultValue = originalValue.clone().add(addedValue);
console.log(`Original value (immutable check): ${originalValue.toString()}`); // Should still be 100
console.log(`Result of clone().add(): ${resultValue.toString()}`); // Should be 150