@toruslabs/metadata-helpers/dist/lib.cjs/helpers/number.js

Helper methods for metadata

'use strict';

var assert = require('./assert.js');
var hex = require('./hex.js');

/**
 * Convert a number to a hexadecimal string. This verifies that the number is a
 * non-negative safe integer.
 *
 * To convert a `bigint` to a hexadecimal string instead, use
 * {@link bigIntToHexPrefixedString}.
 *
 * @example
 * ```typescript
 * numberToHexPrefixedString(16); // '0x10'
 * numberToHexPrefixedString(16, { prefixed: false }); // '10'
 * ```
 * @param value - The number to convert to a hexadecimal string.
 * @param options - Optional. Set `{ prefixed: false }` to omit the "0x" prefix.
 * @returns The hexadecimal string.
 * @throws If the number is not a non-negative safe integer.
 */
const numberToHexPrefixedString = (value, options) => {
  assert.assert(typeof value === "number", "Value must be a number.");
  assert.assert(value >= 0, "Value must be a non-negative number.");
  assert.assert(Number.isSafeInteger(value), "Value is not a safe integer. Use `bigIntToHex` instead.");
  let hex$1 = value.toString(16);
  if (hex$1.length % 2 !== 0) {
    hex$1 = "0" + hex$1;
  }
  return (options === null || options === void 0 ? void 0 : options.prefixed) === false ? hex$1 : hex.add0x(hex$1);
};
/**
 * Convert a `bigint` to a hexadecimal string. This verifies that the `bigint`
 * is a non-negative integer.
 *
 * To convert a number to a hexadecimal string instead, use {@link numberToHexPrefixedString}.
 *
 * @example
 * ```typescript
 * bigIntToHexPrefixedString(16n); // '0x10'
 * bigIntToHexPrefixedString(16n, { prefixed: false }); // '10'
 * ```
 * @param value - The `bigint` to convert to a hexadecimal string.
 * @param options - Optional. Set `{ prefixed: false }` to omit the "0x" prefix.
 * @returns The hexadecimal string.
 * @throws If the `bigint` is not a non-negative integer.
 */
const bigIntToHexPrefixedString = (value, options) => {
  assert.assert(typeof value === "bigint", "Value must be a bigint.");
  assert.assert(value >= 0, "Value must be a non-negative bigint.");
  let hex$1 = value.toString(16);
  if (hex$1.length % 2 !== 0) {
    hex$1 = "0" + hex$1;
  }
  return (options === null || options === void 0 ? void 0 : options.prefixed) === false ? hex$1 : hex.add0x(hex$1);
};
/**
 * Convert a `bigint` to a zero-padded hexadecimal string (torus.js–compatible name).
 * By default returns without "0x" prefix.
 *
 * @example
 * ```typescript
 * bigintToHex(255n); // '00000...00ff' (64 chars, no prefix)
 * bigintToHex(255n, 4, { prefixed: true }); // '0x00ff'
 * ```
 * @param value - The bigint to convert.
 * @param length - Pad to this many hex characters (default 64).
 * @param options - Optional. Set `{ prefixed: true }` to add "0x" prefix.
 * @returns The padded hexadecimal string.
 */
const bigintToHex = (value, length = 64, options) => {
  let hex$1 = value.toString(16).padStart(length, "0");
  if (hex$1.length % 2 !== 0) {
    hex$1 = "0" + hex$1;
  }
  return options !== null && options !== void 0 && options.prefixed ? hex.add0x(hex$1) : hex$1;
};
/** @deprecated Use bigintToHex. Kept for backward compatibility. */
const bigIntToHexPaddedString = bigintToHex;
/**
 * Convert a hexadecimal string to a number. This verifies that the string is a
 * valid hex string, and that the resulting number is a safe integer. Both
 * "0x"-prefixed and unprefixed strings are supported.
 *
 * To convert a hexadecimal string to a `bigint` instead, use
 * {@link hexToBigInt}.
 *
 * @example
 * ```typescript
 * hexToNumber('0x0'); // 0
 * hexToNumber('0x1'); // 1
 * hexToNumber('0x10'); // 16
 * ```
 * @param value - The hexadecimal string to convert to a number.
 * @returns The number.
 * @throws If the value is not a valid hexadecimal string, or if the resulting
 * number is not a safe integer.
 */
const hexToNumber = value => {
  hex.assertIsHexString(value);
  // `parseInt` accepts values without the "0x"-prefix, whereas `Number` does
  // not. Using this is slightly faster than `Number(add0x(value))`.
  const numberValue = parseInt(value, 16);
  assert.assert(Number.isSafeInteger(numberValue), "Value is not a safe integer. Use `hexToBigInt` instead.");
  return numberValue;
};
/**
 * Convert a hexadecimal string to a `bigint`. This verifies that the string is
 * a valid hex string. Both "0x"-prefixed and unprefixed strings are supported.
 *
 * To convert a hexadecimal string to a number instead, use {@link hexToNumber}.
 *
 * @example
 * ```typescript
 * hexToBigInt('0x0'); // 0n
 * hexToBigInt('0x1'); // 1n
 * hexToBigInt('0x10'); // 16n
 * ```
 * @param value - The hexadecimal string to convert to a `bigint`.
 * @returns The `bigint`.
 * @throws If the value is not a valid hexadecimal string.
 */
const hexToBigInt = value => {
  hex.assertIsHexString(value);
  // The `BigInt` constructor requires the "0x"-prefix to parse a hex string.
  return BigInt(hex.add0x(value));
};
/**
 * Convert a hex string (with or without 0x prefix) or bigint to bigint.
 * Returns 0n for empty strings. Useful when parsing node responses where
 * values may be missing or empty.
 *
 * @param val - The hex string or bigint to convert.
 * @returns The bigint value.
 */
const toBigIntBE = val => {
  if (typeof val === "bigint") return val;
  const cleaned = val.replace(/^0x/, "");
  if (!cleaned) return 0n;
  return hexToBigInt(cleaned);
};

exports.bigIntToHexPaddedString = bigIntToHexPaddedString;
exports.bigIntToHexPrefixedString = bigIntToHexPrefixedString;
exports.bigintToHex = bigintToHex;
exports.hexToBigInt = hexToBigInt;
exports.hexToNumber = hexToNumber;
exports.numberToHexPrefixedString = numberToHexPrefixedString;
exports.toBigIntBE = toBigIntBE;