@pezkuwi/util 14.0.1

package/src/hex/addPrefix.ts

@@ -0,0 +1,26 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { HexString } from '../types.js';
+
+import { hexHasPrefix } from './hasPrefix.js';
+
+/**
+ * @name hexAddPrefix
+ * @summary Adds the `0x` prefix to string values.
+ * @description
+ * Returns a `0x` prefixed string from the input value. If the input is already prefixed, it is returned unchanged.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { hexAddPrefix } from '@pezkuwi/util';
+ *
+ * console.log('With prefix', hexAddPrefix('0a0b12')); // => 0x0a0b12
+ * ```
+ */
+export function hexAddPrefix (value?: string | null): HexString {
+  return value && hexHasPrefix(value)
+    ? value
+    : `0x${value && value.length % 2 === 1 ? '0' : ''}${value || ''}`;
+}

package/src/hex/fixLength.spec.ts

@@ -0,0 +1,38 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+import { hexFixLength } from './index.js';
+
+describe('hexFixLength', (): void => {
+  it('returns bitLength === -1 as-is', (): void => {
+    expect(
+      hexFixLength('0x12345678')
+    ).toEqual('0x12345678');
+  });
+
+  it('does not change when bitlength === length', (): void => {
+    expect(
+      hexFixLength('0x12345678', 32)
+    ).toEqual('0x12345678');
+  });
+
+  it('trims values when bitLength > length', (): void => {
+    expect(
+      hexFixLength('0x12345678', 16)
+    ).toEqual('0x5678');
+  });
+
+  it('returns as-is when bitLength < length', (): void => {
+    expect(
+      hexFixLength('0x1234', 32)
+    ).toEqual('0x1234');
+  });
+
+  it('adds zeros when bitLength < length (withPadded)', (): void => {
+    expect(
+      hexFixLength('0x1234', 32, true)
+    ).toEqual('0x00001234');
+  });
+});

package/src/hex/fixLength.ts

@@ -0,0 +1,36 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { HexString } from '../types.js';
+
+import { hexAddPrefix } from './addPrefix.js';
+import { hexStripPrefix } from './stripPrefix.js';
+
+/**
+ * @name hexFixLength
+ * @summary Shifts a hex string to a specific bitLength
+ * @description
+ * Returns a `0x` prefixed string with the specified number of bits contained in the return value. (If bitLength is -1, length checking is not done). Values with more bits are trimmed to the specified length. Input values with less bits are returned as-is by default. When `withPadding` is set, shorter values are padded with `0`.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { hexFixLength } from '@pezkuwi/util';
+ *
+ * console.log('fixed', hexFixLength('0x12', 16)); // => 0x12
+ * console.log('fixed', hexFixLength('0x12', 16, true)); // => 0x0012
+ * console.log('fixed', hexFixLength('0x0012', 8)); // => 0x12
+ * ```
+ */
+export function hexFixLength (value: string, bitLength = -1, withPadding = false): HexString {
+  const strLength = Math.ceil(bitLength / 4);
+  const hexLength = strLength + 2;
+
+  return hexAddPrefix(
+    (bitLength === -1 || value.length === hexLength || (!withPadding && value.length < hexLength))
+      ? hexStripPrefix(value)
+      : (value.length > hexLength)
+        ? hexStripPrefix(value).slice(-1 * strLength)
+        : `${'0'.repeat(strLength)}${hexStripPrefix(value)}`.slice(-1 * strLength)
+  );
+}

package/src/hex/hasPrefix.spec.ts

@@ -0,0 +1,32 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+import { hexHasPrefix } from './index.js';
+
+describe('hexHasPrefix', (): void => {
+  it('returns true when hex prefix is found', (): void => {
+    expect(
+      hexHasPrefix('0x1234')
+    ).toEqual(true);
+  });
+
+  it('returns false when no prefix attached', (): void => {
+    expect(
+      hexHasPrefix('123')
+    ).toEqual(false);
+  });
+
+  it('returns false when null value supplied', (): void => {
+    expect(
+      hexHasPrefix(null)
+    ).toEqual(false);
+  });
+
+  it('returns false when non-string value supplied', (): void => {
+    expect(
+      hexHasPrefix(false as unknown as string)
+    ).toEqual(false);
+  });
+});

package/src/hex/hasPrefix.ts

@@ -0,0 +1,24 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { HexString } from '../types.js';
+
+import { isHex } from '../is/hex.js';
+
+/**
+ * @name hexHasPrefix
+ * @summary Tests for the existence of a `0x` prefix.
+ * @description
+ * Checks for a valid hex input value and if the start matched `0x`
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { hexHasPrefix } from '@pezkuwi/util';
+ *
+ * console.log('has prefix', hexHasPrefix('0x1234')); // => true
+ * ```
+ */
+export function hexHasPrefix (value?: string | null): value is HexString {
+  return !!value && isHex(value, -1);
+}

package/src/hex/index.ts

@@ -0,0 +1,16 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @summary Internal utilities to create and test for hex values
+ */
+
+export { hexAddPrefix } from './addPrefix.js';
+export { hexFixLength } from './fixLength.js';
+export { hexHasPrefix } from './hasPrefix.js';
+export { hexStripPrefix } from './stripPrefix.js';
+export { hexToBigInt } from './toBigInt.js';
+export { hexToBn } from './toBn.js';
+export { hexToNumber } from './toNumber.js';
+export { hexToString } from './toString.js';
+export { hexToU8a } from './toU8a.js';

package/src/hex/stripPrefix.spec.ts

@@ -0,0 +1,44 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+import { hexStripPrefix } from './index.js';
+
+describe('hexStripPrefix', (): void => {
+  it('returns an empty string when null value supplied', (): void => {
+    expect(
+      hexStripPrefix(null)
+    ).toEqual('');
+  });
+
+  it('returns an empty string when 0x value supplied', (): void => {
+    expect(
+      hexStripPrefix('0x')
+    ).toEqual('');
+  });
+
+  it('strips the prefix from hex strings', (): void => {
+    expect(
+      hexStripPrefix('0x1223')
+    ).toEqual('1223');
+  });
+
+  it('strips the prefix from hex strings (non 2 lnegth)', (): void => {
+    expect(
+      hexStripPrefix('0x123')
+    ).toEqual('123');
+  });
+
+  it('returns un-prefixed hex as-is', (): void => {
+    expect(
+      hexStripPrefix('abcd1223')
+    ).toEqual('abcd1223');
+  });
+
+  it('throws when invalid hex', (): void => {
+    expect(
+      () => hexStripPrefix('0x0x01ab')
+    ).toThrow(/Expected hex value to convert/);
+  });
+});

package/src/hex/stripPrefix.ts

@@ -0,0 +1,30 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { REGEX_HEX_NOPREFIX, REGEX_HEX_PREFIXED } from '../is/hex.js';
+
+/**
+ * @name hexStripPrefix
+ * @summary Strips any leading `0x` prefix.
+ * @description
+ * Tests for the existence of a `0x` prefix, and returns the value without the prefix. Un-prefixed values are returned as-is.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { hexStripPrefix } from '@pezkuwi/util';
+ *
+ * console.log('stripped', hexStripPrefix('0x1234')); // => 1234
+ * ```
+ */
+export function hexStripPrefix (value?: string | null): string {
+  if (!value || value === '0x') {
+    return '';
+  } else if (REGEX_HEX_PREFIXED.test(value)) {
+    return value.substring(2);
+  } else if (REGEX_HEX_NOPREFIX.test(value)) {
+    return value;
+  }
+
+  throw new Error(`Expected hex value to convert, found '${value}'`);
+}

package/src/hex/toBigInt.spec.ts

@@ -0,0 +1,74 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+import { hexToBigInt } from './index.js';
+
+describe('hexToBigInt', (): void => {
+  it('converts prefixed hex values to BN', (): void => {
+    expect(
+      hexToBigInt('0x81')
+    ).toEqual(0x81n);
+  });
+
+  it('converts null values to BN(0)', (): void => {
+    expect(
+      hexToBigInt(null)
+    ).toEqual(0n);
+  });
+
+  it('converts 0x values to BN(0)', (): void => {
+    expect(
+      hexToBigInt('0x')
+    ).toEqual(0n);
+  });
+
+  it('should convert with Big Endian by default', (): void => {
+    expect(
+      hexToBigInt('0x0100123456')
+    ).toEqual(0x0100123456n);
+  });
+
+  it('converts 0x values to BN(0) (LE)', (): void => {
+    expect(
+      hexToBigInt('0x', { isLe: true })
+    ).toEqual(0n);
+  });
+
+  it('converts little-endian', (): void => {
+    expect(
+      hexToBigInt('0x4500000000000000', { isLe: true })
+    ).toEqual(69n);
+  });
+
+  it('handles negative numbers (LE)', (): void => {
+    expect(
+      hexToBigInt('0x2efb', { isLe: true, isNegative: true })
+    ).toEqual(-1234n);
+  });
+
+  it('handles negative numbers (BE)', (): void => {
+    expect(
+      hexToBigInt('0xfb2e', { isLe: false, isNegative: true })
+    ).toEqual(-1234n);
+  });
+
+  it('handles negative numbers (LE, 128)', (): void => {
+    expect(
+      hexToBigInt('0x00009c584c491ff2ffffffffffffffff', { isLe: true, isNegative: true })
+    ).toEqual(-1000000000000000000n);
+  });
+
+  it('handles starting zeros correctly (BE)', (): void => {
+    expect(
+      hexToBigInt('0x0000000000000100', { isLe: false })
+    ).toEqual(256n);
+  });
+
+  it('handles starting zeros correctly (LE)', (): void => {
+    expect(
+      hexToBigInt('0x0001000000000000', { isLe: true })
+    ).toEqual(256n);
+  });
+});

package/src/hex/toBigInt.ts

@@ -0,0 +1,19 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { ToBnOptions } from '../types.js';
+
+import { BigInt } from '@pezkuwi/x-bigint';
+
+import { u8aToBigInt } from '../u8a/toBigInt.js';
+import { hexToU8a } from './toU8a.js';
+
+/**
+ * @name hexToBigInt
+ * @summary Creates a BigInt instance object from a hex string.
+ */
+export function hexToBigInt (value?: string | null, { isLe = false, isNegative = false }: ToBnOptions = {}): bigint {
+  return !value || value === '0x'
+    ? BigInt(0)
+    : u8aToBigInt(hexToU8a(value), { isLe, isNegative });
+}

package/src/hex/toBn.spec.ts

@@ -0,0 +1,74 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+import { hexToBn } from './index.js';
+
+describe('hexToBn', (): void => {
+  it('converts prefixed hex values to BN', (): void => {
+    expect(
+      hexToBn('0x81').toString(16)
+    ).toBe('81');
+  });
+
+  it('converts null values to BN(0)', (): void => {
+    expect(
+      hexToBn(null).toNumber()
+    ).toBe(0);
+  });
+
+  it('converts 0x values to BN(0)', (): void => {
+    expect(
+      hexToBn('0x').toNumber()
+    ).toBe(0);
+  });
+
+  it('should convert with Big Endian by default', (): void => {
+    expect(
+      hexToBn('0x0100').toNumber()
+    ).toBe(256);
+  });
+
+  it('converts 0x values to BN(0) (LE)', (): void => {
+    expect(
+      hexToBn('0x', { isLe: true }).toNumber()
+    ).toBe(0);
+  });
+
+  it('converts little-endian', (): void => {
+    expect(
+      hexToBn('0x4500000000000000', { isLe: true }).toNumber()
+    ).toBe(69);
+  });
+
+  it('handles negative numbers (LE)', (): void => {
+    expect(
+      hexToBn('0x2efb', { isLe: true, isNegative: true }).toNumber()
+    ).toBe(-1234);
+  });
+
+  it('handles negative numbers (BE)', (): void => {
+    expect(
+      hexToBn('0xfb2e', { isLe: false, isNegative: true }).toNumber()
+    ).toBe(-1234);
+  });
+
+  it('handles negative numbers (LE, 128)', (): void => {
+    expect(
+      hexToBn('0x00009c584c491ff2ffffffffffffffff', { isLe: true, isNegative: true }).toString()
+    ).toEqual('-1000000000000000000');
+  });
+
+  it('handles starting zeros correctly (BE)', (): void => {
+    expect(
+      hexToBn('0x0000000000000100', { isLe: false }).toNumber()
+    ).toBe(256);
+  });
+
+  it('handles starting zeros correctly (LE)', (): void => {
+    expect(
+      hexToBn('0x0001000000000000', { isLe: true }).toNumber()
+    ).toBe(256);
+  });
+});

package/src/hex/toBn.ts

@@ -0,0 +1,40 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { ToBnOptions } from '../types.js';
+
+import { BN } from '../bn/bn.js';
+import { hexStripPrefix } from './stripPrefix.js';
+
+/**
+ * @name hexToBn
+ * @summary Creates a BN.js object from a hex string.
+ * @description
+ * `null` inputs returns a `BN(0)` result. Hex input values return the actual value converted to a BN. Anything that is not a hex string (including the `0x` prefix) throws an error.
+ * @param _value The value to convert
+ * @param _options Options to pass while converting
+ * @param _options.isLe Convert using Little Endian
+ * @param _options.isNegative Convert using two's complement
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { hexToBn } from '@pezkuwi/util';
+ *
+ * hexToBn('0x123480001f'); // => BN(0x123480001f)
+ * ```
+ */
+export function hexToBn (value?: string | null, { isLe = false, isNegative = false }: ToBnOptions = {}): BN {
+  if (!value || value === '0x') {
+    return new BN(0);
+  }
+
+  const stripped = hexStripPrefix(value);
+  const bn = new BN(stripped, 16, isLe ? 'le' : 'be');
+
+  // fromTwos takes as parameter the number of bits, which is the hex length
+  // multiplied by 4 (2 bytes being 8 bits)
+  return isNegative
+    ? bn.fromTwos(stripped.length * 4)
+    : bn;
+}

package/src/hex/toNumber.spec.ts

@@ -0,0 +1,20 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+import { hexToNumber } from './index.js';
+
+describe('hexToNumber', (): void => {
+  it('converts an empty to NaN', (): void => {
+    expect(
+      hexToNumber()
+    ).toEqual(NaN);
+  });
+
+  it('converts to a number from hex', (): void => {
+    expect(
+      hexToNumber('0x1234')
+    ).toEqual(0x1234);
+  });
+});

package/src/hex/toNumber.ts

@@ -0,0 +1,24 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { hexToBn } from './toBn.js';
+
+/**
+ * @name hexToNumber
+ * @summary Creates a Number value from a Buffer object.
+ * @description
+ * `null` inputs returns an NaN result, `hex` values return the actual value as a `Number`.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { hexToNumber } from '@pezkuwi/util';
+ *
+ * hexToNumber('0x1234'); // => 0x1234
+ * ```
+ */
+export function hexToNumber (value?: string | null): number {
+  return value
+    ? hexToBn(value).toNumber()
+    : NaN;
+}

package/src/hex/toString.spec.ts

@@ -0,0 +1,20 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+import { hexToString } from './index.js';
+
+describe('hexToString', (): void => {
+  it('converts an empty to ""', (): void => {
+    expect(
+      hexToString()
+    ).toEqual('');
+  });
+
+  it('converts to a string from hex', (): void => {
+    expect(
+      hexToString('0x68656c6c6f')
+    ).toEqual('hello');
+  });
+});

package/src/hex/toString.ts

@@ -0,0 +1,25 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { u8aToString } from '../u8a/toString.js';
+import { hexToU8a } from './toU8a.js';
+
+/**
+ * @name hexToU8a
+ * @summary Creates a Uint8Array object from a hex string.
+ * @description
+ * Hex input values return the actual bytes value converted to a string. Anything that is not a hex string (including the `0x` prefix) throws an error.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { hexToString } from '@pezkuwi/util';
+ *
+ * hexToU8a('0x68656c6c6f'); // hello
+ * ```
+ */
+export function hexToString (_value?: string | null): string {
+  return u8aToString(
+    hexToU8a(_value)
+  );
+}

package/src/hex/toU8a.spec.ts

@@ -0,0 +1,76 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+import { perfCmp } from '../test/index.js';
+import { hexToU8a } from './index.js';
+import { hexToU8a as hexToU8aBuffer } from './toU8aBuffer.js';
+
+let ptest = '0x';
+
+for (let i = 0; i < 1_000_000; i++) {
+  ptest += (i % 256).toString(16);
+}
+
+describe('hexToU8a', (): void => {
+  it('returns an empty Uint8Array when null provided', (): void => {
+    expect(
+      hexToU8a(null)
+    ).toHaveLength(0);
+  });
+
+  it('returns an empty Uint8Array when 0x provided', (): void => {
+    expect(
+      hexToU8a('0x')
+    ).toHaveLength(0);
+  });
+
+  it('returns a Uint8Array with the correct values', (): void => {
+    expect(
+      hexToU8a('0x80000a')
+    ).toEqual(
+      new Uint8Array([128, 0, 10])
+    );
+  });
+
+  it('returns a Uint8Array with the correct values (bitLength > provided)', (): void => {
+    expect(
+      hexToU8a('0x80000A', 64)
+    ).toEqual(
+      new Uint8Array([0, 0, 0, 0, 0, 128, 0, 10])
+    );
+  });
+
+  it('returns a Uint8Array with the correct values (bitLength < provided)', (): void => {
+    expect(
+      hexToU8a('0x80000a', 16)
+    ).toEqual(
+      new Uint8Array([128, 0])
+    );
+  });
+
+  it('converts a non-aligned string', (): void => {
+    expect(
+      hexToU8a('0x123')
+    ).toEqual(new Uint8Array([0x12, 0x30]));
+  });
+
+  it('converts known bytes to their correct values', (): void => {
+    expect(
+      hexToU8a('0x68656c6c6f20776f726c64') // hello world (11 bytes, non-aligned)
+    ).toEqual(new Uint8Array([0x68, 0x65, 0x6c, 0x6c, 0x6f, 0x20, 0x77, 0x6f, 0x72, 0x6c, 0x64]));
+  });
+
+  it('converts known bytes to their correct values (upper/lower)', (): void => {
+    expect(
+      hexToU8a('0x68656C6c6f20776F726c64') // hello world (11 bytes, non-aligned)
+    ).toEqual(new Uint8Array([0x68, 0x65, 0x6c, 0x6c, 0x6f, 0x20, 0x77, 0x6f, 0x72, 0x6c, 0x64]));
+  });
+
+  perfCmp('hexToU8a', ['hexToU8aBuffer', 'hexToU8a'], 40, [[ptest]], (s: string, isSecond) =>
+    isSecond
+      ? hexToU8a(s)
+      : hexToU8aBuffer(s)
+  );
+});