@pezkuwi/util 14.0.1

package/src/u8a/toHexBuffer.ts

@@ -0,0 +1,30 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { HexString } from '../types.js';
+
+/**
+ * @name u8aToHex
+ * @summary Creates a hex string from a Uint8Array object.
+ * @description
+ * `UInt8Array` input values return the actual hex string. `null` or `undefined` values returns an `0x` string.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { u8aToHex } from '@pezkuwi/util';
+ *
+ * u8aToHex(new Uint8Array([0x68, 0x65, 0x6c, 0x6c, 0xf])); // 0x68656c0f
+ * ```
+ */
+export function u8aToHex (value?: Uint8Array | null, bitLength = -1, isPrefixed = true): HexString {
+  const length = Math.ceil(bitLength / 8);
+
+  return `${isPrefixed ? '0x' : ''}${
+    !value?.length
+      ? ''
+      : (bitLength > 0 && value.length > length)
+        ? `${Buffer.from(value.subarray(0, length / 2)).toString('hex')}…${Buffer.from(value.subarray(value.length - length / 2)).toString('hex')}`
+        : Buffer.from(value).toString('hex')
+  }` as HexString;
+}

package/src/u8a/toNumber.spec.ts

@@ -0,0 +1,47 @@
+// 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 { u8aToNumber } from './index.js';
+
+const TESTS_NUM = TESTS.filter(([,, numarr]) => numarr.length <= 6);
+
+describe('u8aToNumber', (): void => {
+  describe('empty creation', (): void => {
+    it('handles unsigned (le)', (): void => {
+      expect(
+        u8aToNumber(
+          new Uint8Array()
+        )
+      ).toBe(0);
+    });
+
+    it('handles signed (le)', (): void => {
+      expect(
+        u8aToNumber(
+          new Uint8Array(),
+          { isNegative: true }
+        )
+      ).toBe(0);
+    });
+  });
+
+  describe('conversion tests', (): void => {
+    TESTS_NUM.forEach(([isLe, isNegative, numarr, strval], i): void => {
+      it(`#${i}: creates ${strval} (bitLength=${numarr.length * 8}, isLe=${isLe}, isNegative=${isNegative})`, (): void => {
+        expect(
+          u8aToNumber(
+            new Uint8Array(numarr),
+            { isLe, isNegative }
+          ).toString()
+        ).toBe(strval);
+      });
+    });
+  });
+
+  perf('u8aToNumber (i32)', 750_000, [[new Uint8Array([0x9c, 0x9c, 0x9c, 0x9c])]], (v: Uint8Array) => u8aToNumber(v, { isNegative: true }));
+  perf('u8aToNumber (u32)', 750_000, [[new Uint8Array([0x68, 0x65, 0x6c, 0x6c])]], u8aToNumber);
+});

package/src/u8a/toNumber.ts

@@ -0,0 +1,80 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { ToBnOptions } from '../types.js';
+
+/**
+ * @name u8aToNumber
+ * @summary Creates a number from a Uint8Array object.
+ */
+export function u8aToNumber (value: Uint8Array, { isLe = true, isNegative = false }: ToBnOptions = {}): number {
+  // slice + reverse is expensive, however SCALE is LE by default so this is the path
+  // we are most interested in (the BE is added for the sake of being comprehensive)
+  if (!isLe) {
+    value = value.slice().reverse();
+  }
+
+  const count = value.length;
+
+  // When the value is a i{8, 16, 24, 32, 40, 40} values and the top-most bit
+  // indicates a signed value, we use a two's complement conversion. If one of these
+  // flags are not set, we just do a normal unsigned conversion (the same shortcut
+  // applies in both the u8aTo{BigInt, Bn} conversions as well)
+  if (isNegative && count && (value[count - 1] & 0x80)) {
+    switch (count) {
+      case 0:
+        return 0;
+
+      case 1:
+        return (((value[0] ^ 0x0000_00ff) * -1) - 1);
+
+      case 2:
+        return ((((value[0] + (value[1] << 8)) ^ 0x0000_ffff) * -1) - 1);
+
+      case 3:
+        return ((((value[0] + (value[1] << 8) + (value[2] << 16)) ^ 0x00ff_ffff) * -1) - 1);
+
+      case 4:
+        // for the 3rd byte, we don't << 24 - since JS converts all bitwise operators to
+        // 32-bit, in the case where the top-most bit is set this yields a negative value
+        return ((((value[0] + (value[1] << 8) + (value[2] << 16) + (value[3] * 0x1_00_00_00)) ^ 0xffff_ffff) * -1) - 1);
+
+      case 5:
+        return (((((value[0] + (value[1] << 8) + (value[2] << 16) + (value[3] * 0x1_00_00_00)) ^ 0xffff_ffff) + ((value[4] ^ 0xff) * 0x1_00_00_00_00)) * -1) - 1);
+
+      case 6:
+        return (((((value[0] + (value[1] << 8) + (value[2] << 16) + (value[3] * 0x1_00_00_00)) ^ 0xffff_ffff) + (((value[4] + (value[5] << 8)) ^ 0x0000_ffff) * 0x1_00_00_00_00)) * -1) - 1);
+
+      default:
+        throw new Error('Value more than 48-bits cannot be reliably converted');
+    }
+  }
+
+  switch (count) {
+    case 0:
+      return 0;
+
+    case 1:
+      return value[0];
+
+    case 2:
+      return value[0] + (value[1] << 8);
+
+    case 3:
+      return value[0] + (value[1] << 8) + (value[2] << 16);
+
+    case 4:
+      // for the 3rd byte, we don't << 24 - since JS converts all bitwise operators to
+      // 32-bit, in the case where the top-most bit is set this yields a negative value
+      return value[0] + (value[1] << 8) + (value[2] << 16) + (value[3] * 0x1_00_00_00);
+
+    case 5:
+      return value[0] + (value[1] << 8) + (value[2] << 16) + ((value[3] + (value[4] << 8)) * 0x1_00_00_00);
+
+    case 6:
+      return value[0] + (value[1] << 8) + (value[2] << 16) + ((value[3] + (value[4] << 8) + (value[5] << 16)) * 0x1_00_00_00);
+
+    default:
+      throw new Error('Value more than 48-bits cannot be reliably converted');
+  }
+}

package/src/u8a/toString.spec.ts

@@ -0,0 +1,36 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+import { u8aToString } from './index.js';
+
+describe('u8aToString', (): void => {
+  it('decodes to an empty string for undefined', (): void => {
+    expect(
+      u8aToString()
+    ).toEqual('');
+  });
+
+  it('decodes to an empty string for empty buffer', (): void => {
+    expect(
+      u8aToString(new Uint8Array())
+    ).toEqual('');
+  });
+
+  it('decodes the Uint8Array correctly (ru)', (): void => {
+    expect(
+      u8aToString(
+        new Uint8Array([208, 159, 209, 128, 208, 184, 208, 178, 208, 181, 209, 130, 44, 32, 208, 188, 208, 184, 209, 128, 33])
+      )
+    ).toEqual('Привет, мир!');
+  });
+
+  it('decodes the Uint8Array correctly (en)', (): void => {
+    expect(
+      u8aToString(
+        new Uint8Array([0x68, 0x65, 0x6c, 0x6c, 0x6f, 0x20, 0x77, 0x6f, 0x72, 0x6c, 0x64])
+      )
+    ).toEqual('hello world');
+  });
+});

package/src/u8a/toString.ts

@@ -0,0 +1,26 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { TextDecoder } from '@pezkuwi/x-textdecoder';
+
+const decoder = new TextDecoder('utf-8');
+
+/**
+ * @name u8aToString
+ * @summary Creates a utf-8 string from a Uint8Array object.
+ * @description
+ * `UInt8Array` input values return the actual decoded utf-8 string. `null` or `undefined` values returns an empty string.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { u8aToString } from '@pezkuwi/util';
+ *
+ * u8aToString(new Uint8Array([0x68, 0x65, 0x6c, 0x6c, 0x6f])); // hello
+ * ```
+ */
+export function u8aToString (value?: Uint8Array | null): string {
+  return value
+    ? decoder.decode(value)
+    : '';
+}

package/src/u8a/toU8a.spec.ts

@@ -0,0 +1,63 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+import type { U8aLike } from '../types.js';
+
+import { perf } from '../test/index.js';
+import { u8aToU8a } from './index.js';
+
+const TESTS: [input: U8aLike | null | undefined, output: Uint8Array][] = [
+  ['0x80000a', new Uint8Array([128, 0, 10])],
+  ['abcde fghij', new Uint8Array([97, 98, 99, 100, 101, 32, 102, 103, 104, 105, 106])],
+  [[128, 0, 10, 11, 12], new Uint8Array([128, 0, 10, 11, 12])],
+  [Buffer.from([1, 2, 3, 128, 0, 10, 11, 12]), new Uint8Array([1, 2, 3, 128, 0, 10, 11, 12])],
+  [Buffer.from('80000a', 'hex'), new Uint8Array([128, 0, 10])],
+  // this is where completely invalid data is being passed
+  [123 as unknown as Uint8Array, new Uint8Array([49, 50, 51])]
+];
+
+describe('u8aToU8a', (): void => {
+  it('returns an empty Uint8Array when null/undefined/"" provided', (): void => {
+    expect(u8aToU8a(null)).toHaveLength(0);
+    expect(
+      u8aToU8a()
+    ).toHaveLength(0);
+    expect(
+      u8aToU8a('')
+    ).toHaveLength(0);
+    expect(
+      u8aToU8a('')
+    ).toEqual(new Uint8Array());
+  });
+
+  it('Throw error on null/undefined values on strict checking', () => {
+    expect(() => u8aToU8a(undefined, true)).toThrow('u8aToU8a: Expected non-null, non-undefined value');
+    expect(() => u8aToU8a(null, true)).toThrow('u8aToU8a: Expected non-null, non-undefined value');
+  });
+
+  it('returns a Uint8Array as-is (u8a input)', (): void => {
+    const input = new Uint8Array([128, 0, 10]);
+
+    expect(
+      u8aToU8a(input)
+    ).toEqual(input);
+  });
+
+  describe('conversion tests', (): void => {
+    TESTS.forEach(([input, output], i): void => {
+      it(`#${i}: converts ${input as string} (typeof=${typeof input})`, (): void => {
+        expect(
+          u8aToU8a(input)
+        ).toEqual(
+          output
+        );
+      });
+    });
+  });
+
+  perf('u8aToU8a (hex)', 250_000, [['0x1234']], u8aToU8a);
+  perf('u8aToU8a (str)', 250_000, [['test']], u8aToU8a);
+  perf('u8aToU8a (u8a)', 1_000_000, [[new Uint8Array()]], u8aToU8a);
+});

package/src/u8a/toU8a.ts

@@ -0,0 +1,46 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { U8aLike } from '../types.js';
+
+import { hexToU8a } from '../hex/toU8a.js';
+import { isBuffer } from '../is/buffer.js';
+import { isHex } from '../is/hex.js';
+import { isU8a } from '../is/u8a.js';
+import { stringToU8a } from '../string/toU8a.js';
+
+/**
+ * @name u8aToU8a
+ * @summary Creates a Uint8Array value from a Uint8Array, Buffer, string or hex input.
+ * @description
+ * `null` or `undefined` inputs returns a `[]` result, Uint8Array values returns the value, hex strings returns a Uint8Array representation.
+ * If `strict` is true, `null` or `undefined` will throw an error instead of returning an empty array.
+ * Supports input types: Uint8Array, Buffer, hex string, string, or number array.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { u8aToU8a } from '@pezkuwi/util';
+ *
+ * u8aToU8a(new Uint8Array([0x12, 0x34]); // => Uint8Array([0x12, 0x34])
+ * u8aToU8a(0x1234); // => Uint8Array([0x12, 0x34])
+ * ```
+ */
+export function u8aToU8a (value?: U8aLike | null, strict = false): Uint8Array {
+  if (strict && (value === null || value === undefined)) {
+    throw new Error('u8aToU8a: Expected non-null, non-undefined value');
+  }
+
+  return isU8a(value)
+    // NOTE isBuffer needs to go here since it actually extends
+    // Uint8Array on Node.js environments, so all Buffer are Uint8Array,
+    // but Uint8Array is not Buffer
+    ? isBuffer(value)
+      ? new Uint8Array(value)
+      : value
+    : isHex(value)
+      ? hexToU8a(value)
+      : Array.isArray(value)
+        ? new Uint8Array(value)
+        : stringToU8a(value);
+}

package/src/u8a/wrap.spec.ts

@@ -0,0 +1,139 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+// Originally from https://github.com/polkadot-js/extension/pull/743
+
+import { u8aConcat, u8aEq, u8aToString } from '@pezkuwi/util';
+
+import { U8A_WRAP_ETHEREUM, U8A_WRAP_POSTFIX, U8A_WRAP_PREFIX, u8aUnwrapBytes, u8aWrapBytes } from './wrap.js';
+
+const TEST_DATA = 'this is just some random message that we expect to be wrapped along the way';
+const TEST_ETH = u8aConcat(U8A_WRAP_ETHEREUM, TEST_DATA);
+const TEST_WRAP_EMPTY = `${u8aToString(U8A_WRAP_PREFIX)}${u8aToString(U8A_WRAP_POSTFIX)}`;
+const TEST_WRAP_FULL = `${u8aToString(U8A_WRAP_PREFIX)}${TEST_DATA}${u8aToString(U8A_WRAP_POSTFIX)}`;
+const TEST_WARP_HALF_PRE = `${u8aToString(U8A_WRAP_PREFIX)}${TEST_DATA}`;
+const TEST_WRAP_HALF_POST = `${TEST_DATA}${u8aToString(U8A_WRAP_POSTFIX)}`;
+
+describe('u8aWrapBytes', (): void => {
+  it('wraps empty bytes', (): void => {
+    expect(
+      u8aEq(
+        u8aWrapBytes(new Uint8Array()),
+        u8aConcat(U8A_WRAP_PREFIX, U8A_WRAP_POSTFIX)
+      )
+    ).toBe(true);
+  });
+
+  it('wraps when no wrapping is detected', (): void => {
+    expect(
+      u8aToString(
+        u8aWrapBytes(TEST_DATA)
+      )
+    ).toEqual(TEST_WRAP_FULL);
+  });
+
+  it('wraps when only start wrap is detected', (): void => {
+    expect(
+      u8aToString(
+        u8aWrapBytes(TEST_WARP_HALF_PRE)
+      )
+    ).toEqual(`${u8aToString(U8A_WRAP_PREFIX)}${TEST_WARP_HALF_PRE}${u8aToString(U8A_WRAP_POSTFIX)}`);
+  });
+
+  it('wraps when only end wrap is detected', (): void => {
+    expect(
+      u8aToString(
+        u8aWrapBytes(TEST_WRAP_HALF_POST)
+      )
+    ).toEqual(`${u8aToString(U8A_WRAP_PREFIX)}${TEST_WRAP_HALF_POST}${u8aToString(U8A_WRAP_POSTFIX)}`);
+  });
+
+  it('does not re-wrap when a wrap is already present', (): void => {
+    expect(
+      u8aToString(
+        u8aWrapBytes(TEST_WRAP_FULL)
+      )
+    ).toEqual(TEST_WRAP_FULL);
+  });
+
+  it('does not re-wrap when a wrap (empty data) is already present', (): void => {
+    expect(
+      u8aToString(
+        u8aWrapBytes(TEST_WRAP_EMPTY)
+      )
+    ).toEqual(TEST_WRAP_EMPTY);
+  });
+});
+
+describe('unwrapBytes', (): void => {
+  it('unwraps empty bytes', (): void => {
+    expect(
+      u8aEq(
+        u8aUnwrapBytes(new Uint8Array()),
+        new Uint8Array()
+      )
+    ).toBe(true);
+  });
+
+  it('unwraps when no wrapping is detected', (): void => {
+    expect(
+      u8aToString(
+        u8aUnwrapBytes(TEST_DATA)
+      )
+    ).toEqual(TEST_DATA);
+  });
+
+  it('unwraps when no wrapping is detected (only start)', (): void => {
+    expect(
+      u8aToString(
+        u8aUnwrapBytes(TEST_WARP_HALF_PRE)
+      )
+    ).toEqual(TEST_WARP_HALF_PRE);
+  });
+
+  it('unwraps when no wrapping is detected (only end)', (): void => {
+    expect(
+      u8aToString(
+        u8aUnwrapBytes(TEST_WRAP_HALF_POST)
+      )
+    ).toEqual(TEST_WRAP_HALF_POST);
+  });
+
+  it('unwraps when a wrap is present', (): void => {
+    expect(
+      u8aToString(
+        u8aUnwrapBytes(TEST_WRAP_FULL)
+      )
+    ).toEqual(TEST_DATA);
+  });
+
+  it('unwraps when a an empty wrap is present', (): void => {
+    expect(
+      u8aToString(
+        u8aUnwrapBytes(TEST_WRAP_EMPTY)
+      )
+    ).toEqual('');
+  });
+
+  describe('Ethereum-style', (): void => {
+    it('does not wrap an Ethereum wrap', (): void => {
+      expect(
+        u8aEq(
+          u8aWrapBytes(TEST_ETH),
+          TEST_ETH
+        )
+      ).toBe(true);
+    });
+
+    it('does not unwrap an Ethereum wrap', (): void => {
+      expect(
+        u8aEq(
+          u8aUnwrapBytes(TEST_ETH),
+          TEST_ETH
+        )
+      ).toBe(true);
+    });
+  });
+});

package/src/u8a/wrap.ts

@@ -0,0 +1,65 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+// Originally from https://github.com/polkadot-js/extension/pull/743
+
+import type { U8aLike } from '../types.js';
+
+import { u8aConcatStrict } from './concat.js';
+import { u8aEq } from './eq.js';
+import { u8aToU8a } from './toU8a.js';
+
+/** @internal */
+export const U8A_WRAP_ETHEREUM = /*#__PURE__*/ u8aToU8a('\x19Ethereum Signed Message:\n');
+
+/** @internal */
+export const U8A_WRAP_PREFIX = /*#__PURE__*/ u8aToU8a('<Bytes>');
+
+/** @internal */
+export const U8A_WRAP_POSTFIX = /*#__PURE__*/ u8aToU8a('</Bytes>');
+
+const WRAP_LEN = U8A_WRAP_PREFIX.length + U8A_WRAP_POSTFIX.length;
+
+/** @internal */
+export function u8aIsWrapped (u8a: Uint8Array, withEthereum: boolean): boolean {
+  return (
+    (
+      u8a.length >= WRAP_LEN &&
+      u8aEq(u8a.subarray(0, U8A_WRAP_PREFIX.length), U8A_WRAP_PREFIX) &&
+      u8aEq(u8a.slice(-U8A_WRAP_POSTFIX.length), U8A_WRAP_POSTFIX)
+    ) ||
+    (
+      withEthereum &&
+      u8a.length >= U8A_WRAP_ETHEREUM.length &&
+      u8aEq(u8a.subarray(0, U8A_WRAP_ETHEREUM.length), U8A_WRAP_ETHEREUM)
+    )
+  );
+}
+
+/**
+ * @name u8aUnwrapBytes
+ * @description Removes all <Bytes>...</Bytes> wrappers from the supplied value
+ */
+export function u8aUnwrapBytes (bytes: U8aLike): Uint8Array {
+  const u8a = u8aToU8a(bytes);
+
+  // we don't want to unwrap Ethereum-style wraps
+  return u8aIsWrapped(u8a, false)
+    ? u8a.subarray(U8A_WRAP_PREFIX.length, u8a.length - U8A_WRAP_POSTFIX.length)
+    : u8a;
+}
+
+/**
+ * @name u8aWrapBytes
+ * @description
+ * Adds a <Bytes>...</Bytes> wrapper to the supplied value, if
+ * - We don't already have a Bytes wrapper
+ * - The message is not an Ethereum-style message
+ */
+export function u8aWrapBytes (bytes: U8aLike): Uint8Array {
+  const u8a = u8aToU8a(bytes);
+
+  return u8aIsWrapped(u8a, true)
+    ? u8a
+    : u8aConcatStrict([U8A_WRAP_PREFIX, u8a, U8A_WRAP_POSTFIX]);
+}

package/tsconfig.build.json

@@ -0,0 +1,19 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "baseUrl": "..",
+    "outDir": "./build",
+    "rootDir": "./src"
+  },
+  "exclude": [
+    "**/*.spec.ts",
+    "**/mod.ts"
+  ],
+  "references": [
+    { "path": "../x-bigint/tsconfig.build.json" },
+    { "path": "../x-global/tsconfig.build.json" },
+    { "path": "../x-randomvalues/tsconfig.build.json" },
+    { "path": "../x-textdecoder/tsconfig.build.json" },
+    { "path": "../x-textencoder/tsconfig.build.json" }
+  ]
+}

package/tsconfig.spec.json

@@ -0,0 +1,17 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "baseUrl": "..",
+    "outDir": "./build",
+    "rootDir": "./src",
+    "emitDeclarationOnly": false,
+    "noEmit": true
+  },
+  "include": [
+    "**/*.spec.ts"
+  ],
+  "references": [
+    { "path": "../util/tsconfig.build.json" },
+    { "path": "../x-randomvalues/tsconfig.build.json" }
+  ]
+}