@pezkuwi/util 14.0.1

package/src/bn/consts.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 { BN, BN_HUNDRED, BN_ONE, BN_TEN, BN_THOUSAND, BN_ZERO } from './index.js';
+
+describe('consts', (): void => {
+  it('BN_ZERO equals 0', (): void => {
+    expect(
+      BN_ZERO
+    ).toEqual(new BN(0));
+  });
+
+  it('BN_ONE equals 1', (): void => {
+    expect(
+      BN_ONE
+    ).toEqual(new BN(1));
+  });
+
+  it('BN_TEN equals 10', (): void => {
+    expect(
+      BN_TEN
+    ).toEqual(new BN(10));
+  });
+
+  it('BN_HUNDRED equals 100', (): void => {
+    expect(
+      BN_HUNDRED
+    ).toEqual(new BN(100));
+  });
+
+  it('BN_THOUSAND equals 1000', (): void => {
+    expect(
+      BN_THOUSAND
+    ).toEqual(new BN(1000));
+  });
+});

package/src/bn/consts.ts

@@ -0,0 +1,112 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { BN } from './bn.js';
+
+/**
+ * @name BN_ZERO
+ * @summary BN constant for 0.
+ */
+export const BN_ZERO: BN = /*#__PURE__*/ new BN(0);
+
+/**
+ * @name BN_ONE
+ * @summary BN constant for 1.
+ */
+export const BN_ONE: BN = /*#__PURE__*/ new BN(1);
+
+/**
+ * @name BN_TWO
+ * @summary BN constant for 2.
+ */
+export const BN_TWO: BN = /*#__PURE__*/ new BN(2);
+
+/**
+ * @name BN_THREE
+ * @summary BN constant for 3.
+ */
+export const BN_THREE: BN = /*#__PURE__*/ new BN(3);
+
+/**
+ * @name BN_FOUR
+ * @summary BN constant for 4.
+ */
+export const BN_FOUR: BN = /*#__PURE__*/ new BN(4);
+
+/**
+ * @name BN_FIVE
+ * @summary BN constant for 5.
+ */
+export const BN_FIVE: BN = /*#__PURE__*/ new BN(5);
+
+/**
+ * @name BN_SIX
+ * @summary BN constant for 6.
+ */
+export const BN_SIX: BN = /*#__PURE__*/ new BN(6);
+
+/**
+ * @name BN_SEVEN
+ * @summary BN constant for 7.
+ */
+export const BN_SEVEN: BN = /*#__PURE__*/ new BN(7);
+
+/**
+ * @name BN_EIGHT
+ * @summary BN constant for 8.
+ */
+export const BN_EIGHT: BN = /*#__PURE__*/ new BN(8);
+
+/**
+ * @name BN_NINE
+ * @summary BN constant for 9.
+ */
+export const BN_NINE: BN = /*#__PURE__*/ new BN(9);
+
+/**
+ * @name BN_TEN
+ * @summary BN constant for 10.
+ */
+export const BN_TEN: BN = /*#__PURE__*/ new BN(10);
+
+/**
+ * @name BN_HUNDRED
+ * @summary BN constant for 100.
+ */
+export const BN_HUNDRED: BN = /*#__PURE__*/ new BN(100);
+
+/**
+ * @name BN_THOUSAND
+ * @summary BN constant for 1,000.
+ */
+export const BN_THOUSAND: BN = /*#__PURE__*/ new BN(1_000);
+
+/**
+ * @name BN_MILLION
+ * @summary BN constant for 1,000,000.
+ */
+export const BN_MILLION: BN = /*#__PURE__*/ new BN(1_000_000);
+
+/**
+ * @name BN_BILLION
+ * @summary BN constant for 1,000,000,000.
+ */
+export const BN_BILLION: BN = /*#__PURE__*/ new BN(1_000_000_000);
+
+/**
+ * @name BN_QUINTILL
+ * @summary BN constant for 1,000,000,000,000,000,000.
+ */
+export const BN_QUINTILL: BN = BN_BILLION.mul(BN_BILLION);
+
+/**
+ * @name BN_MAX_INTEGER
+ * @summary BN constant for MAX_SAFE_INTEGER
+ */
+export const BN_MAX_INTEGER: BN = /*#__PURE__*/ new BN(Number.MAX_SAFE_INTEGER);
+
+/**
+ * @name BN_SQRT_MAX_INTEGER
+ * @summary BN constant for Math.sqrt(MAX_SAFE_INTEGER)
+ */
+export const BN_SQRT_MAX_INTEGER: BN = /*#__PURE__*/ new BN(94906265);

package/src/bn/fromHex.spec.ts

@@ -0,0 +1,15 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+import { isFunction } from '../is/function.js';
+import { bnFromHex } from './index.js';
+
+describe('bnFromHex', (): void => {
+  it('exists as a function', (): void => {
+    expect(
+      isFunction(bnFromHex)
+    ).toEqual(true);
+  });
+});

package/src/bn/fromHex.ts

@@ -0,0 +1,4 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+export { hexToBn as bnFromHex } from '../hex/toBn.js';

package/src/bn/index.ts

@@ -0,0 +1,18 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @summary Utility methods to convert to and from `BN` objects
+ */
+
+// all named
+export { BN } from './bn.js';
+export { bnFromHex } from './fromHex.js';
+export { bnMax, bnMin } from './min.js';
+export { bnSqrt } from './sqrt.js';
+export { bnToBn } from './toBn.js';
+export { bnToHex } from './toHex.js';
+export { bnToU8a } from './toU8a.js';
+
+// all starred
+export * from './consts.js';

package/src/bn/max.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 { BN, bnMax } from './index.js';
+
+describe('bnMax', (): void => {
+  it('finds BN maximum (sorted)', (): void => {
+    expect(
+      bnMax(new BN(1), new BN(2), new BN(3))
+    ).toEqual(new BN(3));
+  });
+
+  it('finds BN maximum (unsorted)', (): void => {
+    expect(
+      bnMax(new BN(2), new BN(3), new BN(1))
+    ).toEqual(new BN(3));
+  });
+
+  it('returns a single item', (): void => {
+    expect(
+      bnMax(new BN(1))
+    ).toEqual(new BN(1));
+  });
+
+  it('fails when no items are available', (): void => {
+    expect(
+      () => bnMax()
+    ).toThrow(/Must provide one or more arguments/);
+  });
+});

package/src/bn/min.spec.ts

@@ -0,0 +1,26 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+import { BN, bnMin } from './index.js';
+
+describe('bnMin', (): void => {
+  it('finds BN minimum', (): void => {
+    expect(
+      bnMin(new BN(2), new BN(1), new BN(3))
+    ).toEqual(new BN(1));
+  });
+
+  it('returns a single item', (): void => {
+    expect(
+      bnMin(new BN(1))
+    ).toEqual(new BN(1));
+  });
+
+  it('fails when no items are available', (): void => {
+    expect(
+      () => bnMin()
+    ).toThrow(/Must provide one or more arguments/);
+  });
+});

package/src/bn/min.ts

@@ -0,0 +1,36 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { BN } from './bn.js';
+
+import { createCmp } from '../bi/helpers.js';
+
+/**
+ * @name bnMax
+ * @summary Finds and returns the highest value in an array of BNs.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import BN from 'bn.js';
+ * import { bnMax } from '@pezkuwi/util';
+ *
+ * bnMax([new BN(1), new BN(3), new BN(2)]).toString(); // => '3'
+ * ```
+ */
+export const bnMax = /*#__PURE__*/ createCmp<BN>((a, b) => a.gt(b));
+
+/**
+ * @name bnMin
+ * @summary Finds and returns the smallest value in an array of BNs.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import BN from 'bn.js';
+ * import { bnMin } from '@pezkuwi/util';
+ *
+ * bnMin([new BN(1), new BN(3), new BN(2)]).toString(); // => '1'
+ * ```
+ */
+export const bnMin = /*#__PURE__*/ createCmp<BN>((a, b) => a.lt(b));

package/src/bn/sqrt.spec.ts

@@ -0,0 +1,37 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+import { TESTS } from '../bi/sqrt.spec.js';
+import { BN, BN_SQRT_MAX_INTEGER, bnSqrt } from './index.js';
+
+describe('bnSqrt', (): void => {
+  it('fails on < 0 roots', (): void => {
+    expect(
+      () => bnSqrt(new BN(-1))
+    ).toThrow(/negative numbers is not supported/);
+  });
+
+  it('has the correct constant for sqrt(Number.MAX_SAFE_INTEGER)', (): void => {
+    expect(
+      BN_SQRT_MAX_INTEGER.eq(
+        new BN(
+          ~~Math.sqrt(
+            Number.MAX_SAFE_INTEGER
+          )
+        )
+      )
+    ).toEqual(true);
+  });
+
+  describe('conversion tests', (): void => {
+    TESTS.forEach(([value, expected], i): void => {
+      it(`#${i}: calcs ${expected}`, (): void => {
+        expect(
+          bnSqrt(value).eq(new BN(expected))
+        ).toEqual(true);
+      });
+    });
+  });
+});

package/src/bn/sqrt.ts

@@ -0,0 +1,50 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { ToBn } from '../types.js';
+
+import { BN } from './bn.js';
+import { BN_MAX_INTEGER, BN_ONE, BN_SQRT_MAX_INTEGER } from './consts.js';
+import { bnToBn } from './toBn.js';
+
+/**
+ * @name bnSqrt
+ * @summary Calculates the integer square root of a BN
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import BN from 'bn.js';
+ * import { bnSqrt } from '@pezkuwi/util';
+ *
+ * bnSqrt(new BN(16)).toString(); // => '4'
+ * ```
+ */
+export function bnSqrt <ExtToBn extends ToBn> (value: ExtToBn | BN | bigint | string | number | null): BN {
+  const n = bnToBn(value);
+
+  if (n.isNeg()) {
+    throw new Error('square root of negative numbers is not supported');
+  }
+
+  // https://stackoverflow.com/questions/53683995/javascript-big-integer-square-root/
+  // shortcut <= 2^53 - 1 to use the JS utils
+  if (n.lte(BN_MAX_INTEGER)) {
+    // ~~ More performant version of Math.floor
+    return new BN(~~Math.sqrt(n.toNumber()));
+  }
+
+  // Use sqrt(MAX_SAFE_INTEGER) as starting point. since we already know the
+  // output will be larger than this, we expect this to be a safe start
+  let x0 = BN_SQRT_MAX_INTEGER.clone();
+
+  while (true) {
+    const x1 = n.div(x0).iadd(x0).ishrn(1);
+
+    if (x0.eq(x1) || x0.eq(x1.sub(BN_ONE))) {
+      return x0;
+    }
+
+    x0 = x1;
+  }
+}

package/src/bn/toBn.spec.ts

@@ -0,0 +1,53 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+import { BN, bnToBn } from './index.js';
+
+describe('bnToBn', (): void => {
+  it('converts null values to 0x00', (): void => {
+    expect(
+      bnToBn(null).toNumber()
+    ).toEqual(0);
+  });
+
+  it('converts BN values to BN', (): void => {
+    expect(
+      bnToBn(new BN(128)).toNumber()
+    ).toEqual(128);
+  });
+
+  it('converts BigInt values to BN', (): void => {
+    expect(
+      bnToBn(128821n).toNumber()
+    ).toEqual(128821);
+  });
+
+  it('converts number values to BN', (): void => {
+    expect(
+      bnToBn(128).toNumber()
+    ).toEqual(128);
+  });
+
+  it('converts string to BN', (): void => {
+    expect(
+      bnToBn('123').toNumber()
+    ).toEqual(123);
+  });
+
+  it('converts hex to BN', (): void => {
+    expect(
+      bnToBn('0x0123').toNumber()
+    ).toEqual(0x123);
+  });
+
+  it('converts Compact to BN', (): void => {
+    expect(
+      bnToBn({
+        something: 'test',
+        toBn: (): BN => new BN(1234)
+      }).toNumber()
+    ).toEqual(1234);
+  });
+});

package/src/bn/toBn.ts

@@ -0,0 +1,43 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { ToBigInt, ToBn } from '../types.js';
+
+import { hexToBn } from '../hex/toBn.js';
+import { isBigInt } from '../is/bigInt.js';
+import { isHex } from '../is/hex.js';
+import { isToBigInt } from '../is/toBigInt.js';
+import { isToBn } from '../is/toBn.js';
+import { BN } from './bn.js';
+
+/**
+ * @name bnToBn
+ * @summary Creates a BN value from a BN, bigint, string (base 10 or hex) or number input.
+ * @description
+ * `null` inputs returns a `0x0` result, BN values returns the value, numbers returns a BN representation.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import BN from 'bn.js';
+ * import { bnToBn } from '@pezkuwi/util';
+ *
+ * bnToBn(0x1234); // => BN(0x1234)
+ * bnToBn(new BN(0x1234)); // => BN(0x1234)
+ * ```
+ */
+export function bnToBn <ExtToBn extends ToBigInt | ToBn> (value?: ExtToBn | BN | bigint | string | number | null): BN {
+  return value
+    ? BN.isBN(value)
+      ? value
+      : isHex(value)
+        ? hexToBn(value.toString())
+        : isBigInt(value)
+          ? new BN(value.toString())
+          : isToBn(value)
+            ? value.toBn()
+            : isToBigInt(value)
+              ? new BN(value.toBigInt().toString())
+              : new BN(value)
+    : new BN(0);
+}

package/src/bn/toHex.spec.ts

@@ -0,0 +1,50 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+import { BN, bnToHex } from './index.js';
+
+describe('bnToHex', (): void => {
+  it('converts null values to 0x00', (): void => {
+    expect(
+      bnToHex(null)
+    ).toBe('0x00');
+  });
+
+  it('converts null values to 0x00000000 (with bitLength)', (): void => {
+    expect(
+      bnToHex(null, { bitLength: 32 })
+    ).toBe('0x00000000');
+  });
+
+  it('converts BN values to a prefixed hex representation', (): void => {
+    expect(
+      bnToHex(new BN(128))
+    ).toBe('0x80');
+  });
+
+  it('converts BN values to a prefixed hex representation (bitLength)', (): void => {
+    expect(
+      bnToHex(new BN(128), { bitLength: 16 })
+    ).toBe('0x0080');
+  });
+
+  it('converts BN values to a prefixed hex representation (LE)', (): void => {
+    expect(
+      bnToHex(new BN(128), { bitLength: 16, isLe: true })
+    ).toBe('0x8000');
+  });
+
+  it('handles negative numbers', (): void => {
+    expect(
+      bnToHex(new BN(-1234), { isNegative: true })
+    ).toBe('0xfb2e');
+  });
+
+  it('handles negative numbers (with bitLength)', (): void => {
+    expect(
+      bnToHex(new BN(-1234), { bitLength: 32, isNegative: true })
+    ).toBe('0xfffffb2e');
+  });
+});

package/src/bn/toHex.ts

@@ -0,0 +1,27 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { HexString, NumberOptions, ToBn } from '../types.js';
+import type { BN } from './bn.js';
+
+import { u8aToHex } from '../u8a/index.js';
+import { bnToU8a } from './toU8a.js';
+
+/**
+ * @name bnToHex
+ * @summary Creates a hex value from a BN.js bignumber object.
+ * @description
+ * `null` inputs returns a `0x` result, BN values return the actual value as a `0x` prefixed hex value. Anything that is not a BN object throws an error. With `bitLength` set, it fixes the number to the specified length.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import BN from 'bn.js';
+ * import { bnToHex } from '@pezkuwi/util';
+ *
+ * bnToHex(new BN(0x123456)); // => '0x123456'
+ * ```
+ */
+export function bnToHex <ExtToBn extends ToBn> (value?: ExtToBn | BN | bigint | number | null, { bitLength = -1, isLe = false, isNegative = false }: NumberOptions = {}): HexString {
+  return u8aToHex(bnToU8a(value, { bitLength, isLe, isNegative }));
+}

package/src/bn/toU8a.spec.ts

@@ -0,0 +1,60 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+import { arrayRange } from '../array/index.js';
+import { TESTS } from '../bi/toU8a.spec.js';
+import { perf } from '../test/index.js';
+import { BN, bnToU8a } from './index.js';
+
+const ptest = arrayRange(65536).map((v) => [v]);
+
+describe('bnToU8a', (): void => {
+  it('converts null values to 0x00', (): void => {
+    expect(
+      bnToU8a(null)
+    ).toEqual(new Uint8Array(1));
+  });
+
+  it('converts null values to 0x00000000 (bitLength)', (): void => {
+    expect(
+      bnToU8a(null, { bitLength: 32 })
+    ).toEqual(new Uint8Array([0, 0, 0, 0]));
+  });
+
+  it('converts BN values to a prefixed hex representation', (): void => {
+    expect(
+      bnToU8a(new BN(0x123456), { isLe: false })
+    ).toEqual(new Uint8Array([0x12, 0x34, 0x56]));
+  });
+
+  it('converts BN values to a prefixed hex representation (bitLength)', (): void => {
+    expect(
+      bnToU8a(new BN(0x123456), { bitLength: 32, isLe: false })
+    ).toEqual(new Uint8Array([0x00, 0x12, 0x34, 0x56]));
+  });
+
+  it('converts using little endian (as set)', (): void => {
+    expect(
+      bnToU8a(new BN(0x123456), { bitLength: 32, isLe: true })
+    ).toEqual(new Uint8Array([0x56, 0x34, 0x12, 0x00]));
+  });
+
+  describe('conversion tests', (): void => {
+    TESTS.forEach(([isLe, isNegative, numarr, strval], i): void => {
+      const bitLength = numarr.length * 8;
+
+      it(`#${i}: converts from ${strval} (bitLength=${bitLength}, isLe=${isLe}, isNegative=${isNegative})`, (): void => {
+        expect(
+          bnToU8a(
+            new BN(strval),
+            { bitLength, isLe, isNegative }
+          )
+        ).toEqual(new Uint8Array(numarr));
+      });
+    });
+  });
+
+  perf('bnToU8a', 250000, ptest, bnToU8a);
+});

package/src/bn/toU8a.ts

@@ -0,0 +1,45 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { NumberOptions, ToBn } from '../types.js';
+import type { BN } from './bn.js';
+
+import { bnToBn } from './toBn.js';
+
+const DEFAULT_OPTS: NumberOptions = { bitLength: -1, isLe: true, isNegative: false };
+
+/**
+ * @name bnToU8a
+ * @summary Creates a Uint8Array object from a BN.
+ * @description
+ * `null`/`undefined`/`NaN` inputs returns an empty `Uint8Array` result. `BN` input values return the actual bytes value converted to a `Uint8Array`. Optionally convert using little-endian format if `isLE` is set.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { bnToU8a } from '@pezkuwi/util';
+ *
+ * bnToU8a(new BN(0x1234)); // => [0x12, 0x34]
+ * ```
+ */
+export function bnToU8a <ExtToBn extends ToBn> (value?: ExtToBn | BN | bigint | number | null, { bitLength = -1, isLe = true, isNegative = false } = DEFAULT_OPTS): Uint8Array {
+  const valueBn = bnToBn(value);
+  const byteLength = bitLength === -1
+    ? Math.ceil(valueBn.bitLength() / 8)
+    : Math.ceil((bitLength || 0) / 8);
+
+  if (!value) {
+    return bitLength === -1
+      ? new Uint8Array(1)
+      : new Uint8Array(byteLength);
+  }
+
+  const output = new Uint8Array(byteLength);
+  const bn = isNegative
+    ? valueBn.toTwos(byteLength * 8)
+    : valueBn;
+
+  output.set(bn.toArray(isLe ? 'le' : 'be', byteLength), 0);
+
+  return output;
+}

package/src/buffer/index.ts

@@ -0,0 +1,8 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @summary Utility methods to convert to and from `Buffer` objects
+ */
+
+export { bufferToU8a } from './toU8a.js';

package/src/buffer/toU8a.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 { bufferToU8a } from './index.js';
+
+describe('bufferToU8a', (): void => {
+  it('returns an empty buffer when null provided', (): void => {
+    expect(
+      bufferToU8a(null)
+    ).toEqual(new Uint8Array());
+  });
+
+  it('returns a Uint8Buffer with the correct values', (): void => {
+    expect(
+      bufferToU8a(Buffer.from([128, 0, 10]))
+    ).toEqual(new Uint8Array([128, 0, 10]));
+  });
+});