@pezkuwi/util 14.0.5 → 14.0.6

package/src/u8a/toFloat.ts

@@ -0,0 +1,26 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+interface Options {
+  bitLength?: 32 | 64;
+  isLe?: boolean;
+}
+
+/**
+ * @name u8aToFloat
+ * @description Converts a Uint8Array value into the float (either 32 or 64-bit)
+ * representation.
+ */
+export function u8aToFloat (value: Uint8Array, { bitLength = 32, isLe = true }: Options = {}): number {
+  if (bitLength !== 32 && bitLength !== 64) {
+    throw new Error('Invalid bitLength provided, expected 32 or 64');
+  } else if (value.length < (bitLength / 8)) {
+    throw new Error(`Invalid input buffer provided, expected at least ${bitLength / 8} bytes, found ${value.length}`);
+  }
+
+  const dv = new DataView(value.buffer, value.byteOffset);
+
+  return bitLength === 32
+    ? dv.getFloat32(0, isLe)
+    : dv.getFloat64(0, isLe);
+}

package/src/u8a/toHex.spec.ts

@@ -0,0 +1,94 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { perfCmp } from '../test/index.js';
+import { u8aToHex } from './index.js';
+import { u8aToHex as u8aToHexBuffer } from './toHexBuffer.js';
+
+const ptest32k = new Uint8Array(32768);
+const ptest256 = new Uint8Array(256);
+
+for (let i = 0, count = ptest32k.length; i < count; i++) {
+  if (i < ptest256.length) {
+    ptest256[1] = i % 256;
+  }
+
+  ptest32k[i] = i % 256;
+}
+
+describe('u8aToHex', (): void => {
+  it('returns empty as 0x', (): void => {
+    expect(
+      u8aToHex()
+    ).toEqual('0x');
+  });
+
+  it('returns empty as "" (unprefixed)', (): void => {
+    expect(
+      u8aToHex(null, -1, false)
+    ).toEqual('');
+  });
+
+  it('returns the hex value for the array', (): void => {
+    expect(
+      u8aToHex(
+        new Uint8Array([128, 0, 10])
+      )
+    ).toEqual('0x80000a');
+  });
+
+  it('returns the hex value for the array (unprefixed)', (): void => {
+    expect(
+      u8aToHex(
+        new Uint8Array([128, 0, 10]),
+        -1,
+        false
+      )
+    ).toEqual('80000a');
+  });
+
+  it('handles starting zeros correctly', (): void => {
+    expect(
+      u8aToHex(
+        new Uint8Array([0, 1, 0, 0, 0, 0, 0, 0])
+      )
+    ).toEqual('0x0001000000000000');
+  });
+
+  it('returns the hex value where allowed < max', (): void => {
+    expect(
+      u8aToHex(
+        new Uint8Array(Uint8Array.from([128, 0, 10, 11]), 64)
+      )
+    ).toEqual('0x80000a0b');
+  });
+
+  it('returns the trimmed hex value where allowed >= max', (): void => {
+    expect(
+      u8aToHex(
+        new Uint8Array([128, 0, 10, 11, 12, 13]),
+        32
+      )
+    ).toEqual('0x8000…0c0d');
+  });
+
+  it('converts known bytes to their correct values', (): void => {
+    expect(
+      // hello world
+      u8aToHex(new Uint8Array([0x68, 0x65, 0x6c, 0x6c, 0x6f, 0x20, 0x77, 0x6f, 0x72, 0x6c, 0x64]))
+    ).toEqual('0x68656c6c6f20776f726c64');
+  });
+
+  perfCmp('u8aToHex (32k)', ['u8aToHexBuffer', 'u8aToHex'], 1000, [[ptest32k]], (s: Uint8Array, isSecond) =>
+    isSecond
+      ? u8aToHex(s)
+      : u8aToHexBuffer(s)
+  );
+  perfCmp('u8aToHex (128)', ['u8aToHexBuffer', 'u8aToHex'], 200_000, [[ptest256]], (s: Uint8Array, isSecond) =>
+    isSecond
+      ? u8aToHex(s)
+      : u8aToHexBuffer(s)
+  );
+});

package/src/u8a/toHex.ts

@@ -0,0 +1,68 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { HexString } from '../types.js';
+
+const U8 = new Array<string>(256);
+const U16 = new Array<string>(256 * 256);
+
+for (let n = 0; n < 256; n++) {
+  U8[n] = n.toString(16).padStart(2, '0');
+}
+
+for (let i = 0; i < 256; i++) {
+  const s = i << 8;
+
+  for (let j = 0; j < 256; j++) {
+    U16[s | j] = U8[i] + U8[j];
+  }
+}
+
+/** @internal */
+function hex (value: Uint8Array, result: HexString): HexString {
+  const mod = (value.length % 2) | 0;
+  const length = (value.length - mod) | 0;
+
+  for (let i = 0; i < length; i += 2) {
+    result += U16[(value[i] << 8) | value[i + 1]];
+  }
+
+  if (mod) {
+    result += U8[value[length] | 0];
+  }
+
+  return result;
+}
+
+/**
+ * @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 {
+  // this is not 100% correct sinmce we support isPrefixed = false....
+  const empty = isPrefixed
+    ? '0x'
+    : '' as HexString;
+
+  if (!value?.length) {
+    return empty;
+  } else if (bitLength > 0) {
+    const length = Math.ceil(bitLength / 8);
+
+    if (value.length > length) {
+      return `${hex(value.subarray(0, length / 2), empty)}…${hex(value.subarray(value.length - length / 2), '' as HexString)}`;
+    }
+  }
+
+  return hex(value, empty);
+}

package/src/u8a/toHexBuffer.spec.ts

@@ -0,0 +1,63 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { u8aToHex } from './toHexBuffer.js';
+
+describe('u8aToHex', (): void => {
+  it('returns empty as 0x', (): void => {
+    expect(
+      u8aToHex()
+    ).toEqual('0x');
+  });
+
+  it('returns empty as "" (unprefixed)', (): void => {
+    expect(
+      u8aToHex(null, -1, false)
+    ).toEqual('');
+  });
+
+  it('returns the hex value for the array', (): void => {
+    expect(
+      u8aToHex(
+        new Uint8Array([128, 0, 10])
+      )
+    ).toEqual('0x80000a');
+  });
+
+  it('returns the hex value for the array (unprefixed)', (): void => {
+    expect(
+      u8aToHex(
+        new Uint8Array([128, 0, 10]),
+        -1,
+        false
+      )
+    ).toEqual('80000a');
+  });
+
+  it('handles starting zeros correctly', (): void => {
+    expect(
+      u8aToHex(
+        new Uint8Array([0, 1, 0, 0, 0, 0, 0, 0])
+      )
+    ).toEqual('0x0001000000000000');
+  });
+
+  it('returns the hex value where allowed < max', (): void => {
+    expect(
+      u8aToHex(
+        new Uint8Array(Uint8Array.from([128, 0, 10, 11]), 64)
+      )
+    ).toEqual('0x80000a0b');
+  });
+
+  it('returns the trimmed hex value where allowed >= max', (): void => {
+    expect(
+      u8aToHex(
+        new Uint8Array([128, 0, 10, 11, 12, 13]),
+        32
+      )
+    ).toEqual('0x8000…0c0d');
+  });
+});

package/src/u8a/toHexBuffer.ts

@@ -0,0 +1,30 @@
+// Copyright 2017-2025 @pezkuwi/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 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/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 @pezkuwi/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 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/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 @pezkuwi/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 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/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 @pezkuwi/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);
+}