@pezkuwi/util 14.0.1

package/src/u8a/concat.spec.ts

@@ -0,0 +1,42 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+import { getRandomValues } from '@pezkuwi/x-randomvalues';
+
+import { arrayRange } from '../array/index.js';
+import { perf } from '../test/index.js';
+import { u8aConcat, u8aConcatStrict } from './index.js';
+
+const ptest = arrayRange(10).map(() => getRandomValues(new Uint8Array(32)));
+
+describe('u8aConcat', (): void => {
+  it('concatenates arrays', (): void => {
+    expect(
+      u8aConcat(
+        new Uint8Array([1, 2, 3, 4]),
+        new Uint8Array([5, 6]),
+        new Uint8Array([7, 8, 9])
+      )
+    ).toEqual(
+      new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9])
+    );
+  });
+
+  it('concatenates arrays & hex values', (): void => {
+    expect(
+      u8aConcat(
+        new Uint8Array([1, 2, 3, 4]),
+        '0x0506',
+        '0x070809'
+      )
+    ).toEqual(
+      new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9])
+    );
+  });
+
+  perf('u8aConcat', 10000, [[ptest]], u8aConcat);
+  perf('u8aConcatStrict', 10000, [[[ptest]]], u8aConcatStrict);
+  perf('u8aConcatStrict (len)', 10000, [[[ptest], 320]], u8aConcatStrict);
+});

package/src/u8a/concat.ts

@@ -0,0 +1,60 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { U8aLike } from '../types.js';
+
+import { u8aToU8a } from './toU8a.js';
+
+/**
+ * @name u8aConcat
+ * @summary Creates a concatenated Uint8Array from the inputs.
+ * @description
+ * Concatenates the input arrays into a single `UInt8Array`.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { { u8aConcat } from '@pezkuwi/util';
+ *
+ * u8aConcat(
+ *   new Uint8Array([1, 2, 3]),
+ *   new Uint8Array([4, 5, 6])
+ * ); // [1, 2, 3, 4, 5, 6]
+ * ```
+ */
+export function u8aConcat (...list: readonly U8aLike[]): Uint8Array {
+  const count = list.length;
+  const u8as = new Array<Uint8Array>(count);
+  let length = 0;
+
+  for (let i = 0; i < count; i++) {
+    u8as[i] = u8aToU8a(list[i]);
+    length += u8as[i].length;
+  }
+
+  return u8aConcatStrict(u8as, length);
+}
+
+/**
+ * @name u8aConcatStrict
+ * @description A strict version of [[u8aConcat]], accepting only Uint8Array inputs
+ */
+export function u8aConcatStrict (u8as: readonly Uint8Array[], length = 0): Uint8Array {
+  const count = u8as.length;
+  let offset = 0;
+
+  if (!length) {
+    for (let i = 0; i < count; i++) {
+      length += u8as[i].length;
+    }
+  }
+
+  const result = new Uint8Array(length);
+
+  for (let i = 0; i < count; i++) {
+    result.set(u8as[i], offset);
+    offset += u8as[i].length;
+  }
+
+  return result;
+}

package/src/u8a/concatBuffer.ts

@@ -0,0 +1,34 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { U8aLike } from '../types.js';
+
+import { u8aToU8a } from './toU8a.js';
+
+/**
+ * @name u8aConcat
+ * @summary Creates a concatenated Uint8Array from the inputs.
+ * @description
+ * Concatenates the input arrays into a single `UInt8Array`.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { { u8aConcat } from '@pezkuwi/util';
+ *
+ * u8aConcat(
+ *   new Uint8Array([1, 2, 3]),
+ *   new Uint8Array([4, 5, 6])
+ * ); // [1, 2, 3, 4, 5, 6]
+ * ```
+ */
+export function u8aConcat (...list: readonly U8aLike[]): Uint8Array {
+  const count = list.length;
+  const u8as = new Array<Uint8Array>(count);
+
+  for (let i = 0; i < count; i++) {
+    u8as[i] = u8aToU8a(list[i]);
+  }
+
+  return Uint8Array.from(Buffer.concat(u8as));
+}

package/src/u8a/empty.spec.ts

@@ -0,0 +1,46 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+import { perf } from '../test/index.js';
+import { u8aEmpty } from './index.js';
+
+describe('u8aEmpty', (): void => {
+  it('returns true on zero length', (): void => {
+    expect(
+      u8aEmpty(new Uint8Array())
+    ).toEqual(true);
+  });
+
+  it('returns true on all zero values', (): void => {
+    expect(
+      u8aEmpty(new Uint8Array([0, 0, 0, 0, 0, 0]))
+    ).toEqual(true);
+  });
+
+  it('returns false when value is found', (): void => {
+    expect(
+      u8aEmpty(new Uint8Array([0, 0, 0, 0, 0, 1]))
+    ).toEqual(false);
+  });
+
+  it('returns false when value is found (256)', (): void => {
+    const test = new Uint8Array(256);
+
+    expect(
+      u8aEmpty(test)
+    ).toEqual(true);
+
+    test[128] = 1;
+
+    expect(
+      u8aEmpty(test)
+    ).toEqual(false);
+  });
+
+  perf('u8aEmpty (32 cmp)', 1_000_000, [[new Uint8Array(32)]], u8aEmpty);
+  perf('u8aEmpty (64 cmp)', 500_000, [[new Uint8Array(64)]], u8aEmpty);
+  perf('u8aEmpty (128 cmp)', 250_000, [[new Uint8Array(128)]], u8aEmpty);
+  perf('u8aEmpty (256 cmp)', 125_000, [[new Uint8Array(256)]], u8aEmpty);
+});

package/src/u8a/empty.ts

@@ -0,0 +1,22 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @name u8aEmpty
+ * @summary Tests for a `Uint8Array` for emptyness
+ * @description
+ * Checks to see if the input `Uint8Array` has zero length or contains all 0 values.
+ */
+export function u8aEmpty (value: Uint8Array): boolean {
+  const len = value.length | 0;
+
+  // on smaller sizes, the byte-by-byte compare is faster than allocating
+  // another object for DataView (on very large arrays the DataView is faster)
+  for (let i = 0; i < len; i++) {
+    if (value[i] | 0) {
+      return false;
+    }
+  }
+
+  return true;
+}

package/src/u8a/eq.spec.ts

@@ -0,0 +1,113 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+import { perf } from '../test/index.js';
+import { u8aEq } from './index.js';
+
+const ltest = new Uint8Array(32768);
+const stest = new Uint8Array(256);
+const ztest = new Uint8Array(64);
+
+for (let i = 0, count = ltest.length; i < count; i++) {
+  if (i < ztest.length) {
+    ztest[i] = i % 256;
+  }
+
+  if (i < stest.length) {
+    stest[i] = i % 256;
+  }
+
+  ltest[i] = i % 256;
+}
+
+describe('u8aEq', (): void => {
+  it('returns false when the lengths do not match', (): void => {
+    expect(
+      u8aEq(
+        new Uint8Array([1, 2, 3]),
+        new Uint8Array([1, 2])
+      )
+    ).toEqual(false);
+  });
+
+  it('returns false when the contents do not match', (): void => {
+    expect(
+      u8aEq(
+        new Uint8Array([1, 2, 3]),
+        new Uint8Array([1, 2, 4])
+      )
+    ).toEqual(false);
+  });
+
+  it('returns true when the contents do match', (): void => {
+    expect(
+      u8aEq(
+        new Uint8Array([1, 2, 3]),
+        new Uint8Array([1, 2, 3])
+      )
+    ).toEqual(true);
+  });
+
+  it('returns false when the contents do not match (with u32 start)', (): void => {
+    expect(
+      u8aEq(
+        new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 1, 2, 3]),
+        new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 1, 2, 4])
+      )
+    ).toEqual(false);
+  });
+
+  it('returns true when the contents do match (with u32 start)', (): void => {
+    expect(
+      u8aEq(
+        new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 1, 2, 3]),
+        new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 1, 2, 3])
+      )
+    ).toEqual(true);
+  });
+
+  it('returns false when the contents do not match (u32 only)', (): void => {
+    expect(
+      u8aEq(
+        new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]),
+        new Uint8Array([1, 2, 3, 4, 5, 6, 7, 9])
+      )
+    ).toEqual(false);
+  });
+
+  it('returns true when the contents do match (u32 only)', (): void => {
+    expect(
+      u8aEq(
+        new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]),
+        new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8])
+      )
+    ).toEqual(true);
+  });
+
+  it('returns true with equalvalent hex & Uint8array', (): void => {
+    expect(
+      u8aEq(
+        '0x010203',
+        new Uint8Array([1, 2, 3])
+      )
+    ).toEqual(true);
+  });
+
+  it('works on aubarray values', (): void => {
+    const a = new Uint8Array(16);
+
+    for (let i = 0, count = a.length; i < count; i++) {
+      a[i] = i;
+    }
+
+    expect(
+      u8aEq(a.subarray(0, 5), a.subarray(0, 5))
+    ).toEqual(true);
+  });
+
+  perf('u8aEq (64 cmp)', 200_000, [[ztest, ztest]], u8aEq);
+  perf('u8aEq (256 cmp)', 200_000, [[stest, stest]], u8aEq);
+  perf('u8aEq (32k cmp)', 10_000, [[ltest, ltest]], u8aEq);
+});

package/src/u8a/eq.ts

@@ -0,0 +1,46 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { u8aToU8a } from './toU8a.js';
+
+/**
+ * @name u8aEq
+ * @summary Compares two Uint8Arrays for equality.
+ * @description
+ * For `UInt8Array` (or hex string) input values true if there is a match.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { u8aEq } from '@pezkuwi/util';
+ *
+ * u8aEq(new Uint8Array([0x68, 0x65]), new Uint8Array([0x68, 0x65])); // true
+ * ```
+ */
+export function u8aEq (a: string | Uint8Array, b: string | Uint8Array): boolean {
+  const u8aa = u8aToU8a(a);
+  const u8ab = u8aToU8a(b);
+
+  if (u8aa.length === u8ab.length) {
+    const dvA = new DataView(u8aa.buffer, u8aa.byteOffset);
+    const dvB = new DataView(u8ab.buffer, u8ab.byteOffset);
+    const mod = (u8aa.length % 4) | 0;
+    const length = (u8aa.length - mod) | 0;
+
+    for (let i = 0; i < length; i += 4) {
+      if (dvA.getUint32(i) !== dvB.getUint32(i)) {
+        return false;
+      }
+    }
+
+    for (let i = length, count = u8aa.length; i < count; i++) {
+      if (u8aa[i] !== u8ab[i]) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  return false;
+}

package/src/u8a/fixLength.spec.ts

@@ -0,0 +1,34 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+import { u8aFixLength } from './index.js';
+
+describe('u8aFixLength', (): void => {
+  it('returns bitLength === -1 as-is', (): void => {
+    expect(
+      u8aFixLength(
+        new Uint8Array([0x12, 0x34, 0x56, 0x78])
+      )
+    ).toEqual(new Uint8Array([0x12, 0x34, 0x56, 0x78]));
+  });
+
+  it('does not change when bitlength === length', (): void => {
+    expect(
+      u8aFixLength(new Uint8Array([0x12, 0x34, 0x56, 0x78]), 32)
+    ).toEqual(new Uint8Array([0x12, 0x34, 0x56, 0x78]));
+  });
+
+  it('trims values when bitLength > length', (): void => {
+    expect(
+      u8aFixLength(new Uint8Array([0x12, 0x34, 0x56, 0x78]), 16)
+    ).toEqual(new Uint8Array([0x12, 0x34]));
+  });
+
+  it('adds zeros when bitLength < length (withPadded)', (): void => {
+    expect(
+      u8aFixLength(new Uint8Array([0x12, 0x34]), 32)
+    ).toEqual(new Uint8Array([0, 0, 0x12, 0x34]));
+  });
+});

package/src/u8a/fixLength.ts

@@ -0,0 +1,34 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @name u8aFixLength
+ * @summary Shifts a Uint8Array to a specific bitLength
+ * @description
+ * Returns a uint8Array 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.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { u8aFixLength } from '@pezkuwi/util';
+ *
+ * u8aFixLength('0x12') // => 0x12
+ * u8aFixLength('0x12', 16) // => 0x0012
+ * u8aFixLength('0x1234', 8) // => 0x12
+ * ```
+ */
+export function u8aFixLength (value: Uint8Array, bitLength = -1, atStart = false): Uint8Array {
+  const byteLength = Math.ceil(bitLength / 8);
+
+  if (bitLength === -1 || value.length === byteLength) {
+    return value;
+  } else if (value.length > byteLength) {
+    return value.subarray(0, byteLength);
+  }
+
+  const result = new Uint8Array(byteLength);
+
+  result.set(value, atStart ? 0 : (byteLength - value.length));
+
+  return result;
+}

package/src/u8a/index.ts

@@ -0,0 +1,22 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @summary Utility methods to convert to and from `Uint8Array` objects
+ */
+
+export { u8aCmp } from './cmp.js';
+export { u8aConcat, u8aConcatStrict } from './concat.js';
+export { u8aEmpty } from './empty.js';
+export { u8aEq } from './eq.js';
+export { u8aFixLength } from './fixLength.js';
+export { u8aSorted } from './sorted.js';
+export { u8aToBigInt } from './toBigInt.js';
+export { u8aToBn } from './toBn.js';
+export { u8aToBuffer } from './toBuffer.js';
+export { u8aToFloat } from './toFloat.js';
+export { u8aToHex } from './toHex.js';
+export { u8aToNumber } from './toNumber.js';
+export { u8aToString } from './toString.js';
+export { u8aToU8a } from './toU8a.js';
+export { U8A_WRAP_ETHEREUM, U8A_WRAP_POSTFIX, U8A_WRAP_PREFIX, u8aIsWrapped, u8aUnwrapBytes, u8aWrapBytes } from './wrap.js';

package/src/u8a/sorted.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 { u8aSorted } from './index.js';
+
+describe('u8aSorted', (): void => {
+  it('sorts a simple set of u8a', (): void => {
+    expect(
+      u8aSorted([new Uint8Array([1, 2, 3]), new Uint8Array([4, 5, 6]), new Uint8Array([2, 3, 4])])
+    ).toEqual([new Uint8Array([1, 2, 3]), new Uint8Array([2, 3, 4]), new Uint8Array([4, 5, 6])]);
+  });
+
+  it('sorts a simple set of u8a (not the same lengths)', (): void => {
+    expect(
+      u8aSorted([new Uint8Array([1, 2, 3, 4]), new Uint8Array([4, 5, 6]), new Uint8Array([1, 2, 3, 5])])
+    ).toEqual([new Uint8Array([1, 2, 3, 4]), new Uint8Array([1, 2, 3, 5]), new Uint8Array([4, 5, 6])]);
+  });
+});

package/src/u8a/sorted.ts

@@ -0,0 +1,22 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { u8aCmp } from './cmp.js';
+
+/**
+ * @name u8aSorted
+ * @summary Sorts an array of Uint8Arrays
+ * @description
+ * For input `UInt8Array[]` return the sorted result
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { u8aSorted} from '@pezkuwi/util';
+ *
+ * u8aSorted([new Uint8Array([0x69]), new Uint8Array([0x68])]); // [0x68, 0x69]
+ * ```
+ */
+export function u8aSorted (u8as: Uint8Array[]): Uint8Array[] {
+  return u8as.sort(u8aCmp);
+}

package/src/u8a/toBigInt.spec.ts

@@ -0,0 +1,106 @@
+// 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/toU8a.spec.js';
+import { perf } from '../test/index.js';
+import { u8aToBigInt } from './index.js';
+
+// test-cases are the same as in u8aToBn
+describe('u8aToBigInt', (): void => {
+  it('converts little-endian by default', (): void => {
+    expect(
+      u8aToBigInt(
+        new Uint8Array([0x12, 0x34])
+      ).toString(16)
+    ).toBe('3412');
+  });
+
+  describe('empty creation', (): void => {
+    it('handles unsigned (le)', (): void => {
+      expect(
+        u8aToBigInt(
+          new Uint8Array(),
+          { isLe: true }
+        ).toString(16)
+      ).toBe('0');
+    });
+
+    it('handles signed (le)', (): void => {
+      expect(
+        u8aToBigInt(
+          new Uint8Array(),
+          { isLe: true, isNegative: true }
+        ).toString(16)
+      ).toBe('0');
+    });
+
+    it('handles unsigned (be)', (): void => {
+      expect(
+        u8aToBigInt(
+          new Uint8Array(),
+          { isLe: false }
+        ).toString(16)
+      ).toBe('0');
+    });
+
+    it('handles signed (be)', (): void => {
+      expect(
+        u8aToBigInt(
+          new Uint8Array(),
+          { isLe: false, isNegative: true }
+        ).toString(16)
+      ).toBe('0');
+    });
+  });
+
+  it('handles overflows correctly (little-endian)', (): void => {
+    expect(
+      u8aToBigInt(
+        new Uint8Array([0, 1, 0, 0, 0, 0, 0, 0]),
+        { isLe: true }
+      )
+    ).toBe(256n);
+  });
+
+  describe('length tests', (): void => {
+    [true, false].forEach((isLe) => {
+      for (let i = 1; i < 32; i++) {
+        const tu8a = [0x12, 0x34, 0x56, 0x78, 0x12, 0x34, 0x56, 0x78, 0x12, 0x34, 0x56, 0x78, 0x12, 0x34, 0x56, 0x78, 0x12, 0x34, 0x56, 0x78, 0x12, 0x34, 0x56, 0x78, 0x12, 0x34, 0x56, 0x78, 0x12, 0x34, 0x56, 0x78];
+        const tstr = tu8a.map((n) => n.toString(16));
+
+        it(`converts values with bitLength=${i * 8}, isLe=${isLe}`, (): void => {
+          expect(
+            u8aToBigInt(
+              new Uint8Array(tu8a.slice(0, i)),
+              { isLe }
+            ).toString(16)
+          ).toBe(
+            isLe
+              ? tstr.slice(0, i).reverse().join('')
+              : tstr.slice(0, i).join('')
+          );
+        });
+      }
+    });
+  });
+
+  describe('conversion tests', (): void => {
+    TESTS.forEach(([isLe, isNegative, numarr, strval], i): void => {
+      it(`#${i}: creates ${strval} (bitLength=${numarr.length * 8}, isLe=${isLe}, isNegative=${isNegative})`, (): void => {
+        expect(
+          u8aToBigInt(
+            new Uint8Array(numarr),
+            { isLe, isNegative }
+          ).toString()
+        ).toBe(strval);
+      });
+    });
+  });
+
+  perf('u8aToBigInt (i32)', 750_000, [[new Uint8Array([0x9c, 0x9c, 0x9c, 0x9c])]], (v: Uint8Array) => u8aToBigInt(v, { isNegative: true }));
+  perf('u8aToBigInt (u32)', 750_000, [[new Uint8Array([0x68, 0x65, 0x6c, 0x6c])]], u8aToBigInt);
+  perf('u8aToBigInt (u64)', 750_000, [[new Uint8Array([0x68, 0x65, 0x6c, 0x6c, 0x68, 0x65, 0x6c, 0x6c])]], u8aToBigInt);
+  perf('u8aToBigInt (u128)', 750_000, [[new Uint8Array([0x68, 0x65, 0x6c, 0x6c, 0x68, 0x65, 0x6c, 0x6c, 0x68, 0x65, 0x6c, 0x6c, 0x68, 0x65, 0x6c, 0x6c])]], u8aToBigInt);
+});