@pezkuwi/util 14.0.1 → 14.0.4

package/u8a/toU8a.d.ts

@@ -0,0 +1,19 @@
+import type { U8aLike } from '../types.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 '@polkadot/util';
+ *
+ * u8aToU8a(new Uint8Array([0x12, 0x34]); // => Uint8Array([0x12, 0x34])
+ * u8aToU8a(0x1234); // => Uint8Array([0x12, 0x34])
+ * ```
+ */
+export declare function u8aToU8a(value?: U8aLike | null, strict?: boolean): Uint8Array;

package/{src/u8a/toU8a.ts → u8a/toU8a.js}

@@ -1,14 +1,8 @@
-// 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.
@@ -26,21 +20,20 @@ import { stringToU8a } from '../string/toU8a.js';
  * 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);
+export function u8aToU8a(value, strict = false) {
+    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/u8a/wrap.d.ts

@@ -0,0 +1,22 @@
+import type { U8aLike } from '../types.js';
+/** @internal */
+export declare const U8A_WRAP_ETHEREUM: Uint8Array;
+/** @internal */
+export declare const U8A_WRAP_PREFIX: Uint8Array;
+/** @internal */
+export declare const U8A_WRAP_POSTFIX: Uint8Array;
+/** @internal */
+export declare function u8aIsWrapped(u8a: Uint8Array, withEthereum: boolean): boolean;
+/**
+ * @name u8aUnwrapBytes
+ * @description Removes all <Bytes>...</Bytes> wrappers from the supplied value
+ */
+export declare function u8aUnwrapBytes(bytes: U8aLike): Uint8Array;
+/**
+ * @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 declare function u8aWrapBytes(bytes: U8aLike): Uint8Array;

package/u8a/wrap.js

@@ -0,0 +1,43 @@
+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, withEthereum) {
+    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) {
+    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) {
+    const u8a = u8aToU8a(bytes);
+    return u8aIsWrapped(u8a, true)
+        ? u8a
+        : u8aConcatStrict([U8A_WRAP_PREFIX, u8a, U8A_WRAP_POSTFIX]);
+}

package/src/array/chunk.spec.ts

@@ -1,29 +0,0 @@
-// Copyright 2017-2025 @polkadot/util authors & contributors
-// SPDX-License-Identifier: Apache-2.0
-
-/// <reference types="@polkadot/dev-test/globals.d.ts" />
-
-import { arrayChunk, arrayRange } from '../index.js';
-import { perf } from '../test/index.js';
-
-describe('arrayChunk', (): void => {
-  it('chunks with exact', (): void => {
-    expect(
-      arrayChunk([1, 2, 3, 4, 5, 6, 7, 8], 8)
-    ).toEqual([[1, 2, 3, 4, 5, 6, 7, 8]]);
-  });
-
-  it('chunks with unequal', (): void => {
-    expect(
-      arrayChunk([1, 2, 3, 4, 5, 6, 7], 3)
-    ).toEqual([[1, 2, 3], [4, 5, 6], [7]]);
-  });
-
-  it('chunks with non-empty results', (): void => {
-    expect(
-      arrayChunk([[1, 2], [3, 4], [5, 6], [7, 8]], 2)
-    ).toEqual([[[1, 2], [3, 4]], [[5, 6], [7, 8]]]);
-  });
-
-  perf('arrayChunk', 200_000, [[arrayRange(500), 50]], arrayChunk);
-});

package/src/array/chunk.ts

@@ -1,35 +0,0 @@
-// Copyright 2017-2025 @polkadot/util authors & contributors
-// SPDX-License-Identifier: Apache-2.0
-
-/**
- * @name arrayChunk
- * @summary Split T[] into T[][] based on the defind size
- * @description
- * Returns a set ao arrays based on the chunksize
- * @example
- * <BR>
- *
- * ```javascript
- * import { arrayChunk } from '@pezkuwi/util';
- *
- * arrayChunk([1, 2, 3, 4, 5]); // [[1, 2], [3, 4], [5]]
- * ```
- */
-export function arrayChunk <T> (array: T[], chunkSize: number): T[][] {
-  const outputSize = Math.ceil(array.length / chunkSize);
-
-  // shortcut for the single-split case
-  if (outputSize === 1) {
-    return [array];
-  }
-
-  const output = Array<T[]>(outputSize);
-
-  for (let i = 0; i < outputSize; i++) {
-    const offset = i * chunkSize;
-
-    output[i] = array.slice(offset, offset + chunkSize);
-  }
-
-  return output;
-}

package/src/array/filter.spec.ts

@@ -1,20 +0,0 @@
-// Copyright 2017-2025 @polkadot/util authors & contributors
-// SPDX-License-Identifier: Apache-2.0
-
-/// <reference types="@polkadot/dev-test/globals.d.ts" />
-
-import { arrayFilter } from './index.js';
-
-describe('filterArray', (): void => {
-  it('filters arrays, removing undefined', (): void => {
-    expect(
-      arrayFilter([0, '', null, false, undefined, NaN])
-    ).toEqual([0, '', null, false, NaN]);
-  });
-
-  it('filters arrays, removing undefined & null (allowNull = false)', (): void => {
-    expect(
-      arrayFilter([0, '', null, false, undefined, NaN], false)
-    ).toEqual([0, '', false, NaN]);
-  });
-});

package/src/array/flatten.spec.ts

@@ -1,33 +0,0 @@
-// 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 { arrayFlatten } from './index.js';
-
-const PERF_ONE = [[1, 2, 3, 4, 5]];
-const PERF_MUL = [[1, 2, 3], [4, 5, 6], [7, 8, 9]];
-
-describe('arrayFlatten', (): void => {
-  it('flattens arrays', (): void => {
-    expect(
-      arrayFlatten([[0], [1, 2, 3], [4, 5], [6], [], [7, 8]])
-    ).toEqual([0, 1, 2, 3, 4, 5, 6, 7, 8]);
-  });
-
-  it('flattens a single entry', (): void => {
-    expect(
-      arrayFlatten([[1, 2, 3, 4, 5]])
-    ).toEqual([1, 2, 3, 4, 5]);
-  });
-
-  it('flattens an empty', (): void => {
-    expect(
-      arrayFlatten([])
-    ).toEqual([]);
-  });
-
-  perf('arrayFlatten (single)', 10_000_000, [[PERF_ONE]], arrayFlatten);
-  perf('arrayFlatten (multi)', 700_000, [[PERF_MUL]], arrayFlatten);
-});

package/src/array/flatten.ts

@@ -1,51 +0,0 @@
-// Copyright 2017-2025 @polkadot/util authors & contributors
-// SPDX-License-Identifier: Apache-2.0
-
-// This is supposed to be a faster concat...
-// https://dev.to/uilicious/javascript-array-push-is-945x-faster-than-array-concat-1oki
-
-/**
- * @name arrayFlatten
- * @summary Merge T[][] into T[]
- * @description
- * Returns a new array with all arrays merged into one
- * @example
- * <BR>
- *
- * ```javascript
- * import { arrayFlatten } from '@pezkuwi/util';
- *
- * arrayFlatten([[1, 2], [3, 4], [5]]); // [1, 2, 3, 4, 5]
- * ```
- */
-export function arrayFlatten <T> (arrays: readonly T[][]): T[] {
-  const num = arrays.length;
-
-  // shortcuts for the empty & single-entry case
-  if (num === 0) {
-    return [];
-  } else if (num === 1) {
-    return arrays[0];
-  }
-
-  // pre-allocate based on the combined size
-  let size = 0;
-
-  for (let i = 0; i < num; i++) {
-    size += arrays[i].length;
-  }
-
-  const output = new Array<T>(size);
-  let i = -1;
-
-  for (let j = 0; j < num; j++) {
-    const a = arrays[j];
-
-    // instead of pushing, we just set the entries
-    for (let e = 0, count = a.length; e < count; e++) {
-      output[++i] = a[e];
-    }
-  }
-
-  return output;
-}

package/src/array/range.spec.ts

@@ -1,29 +0,0 @@
-// 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 { arrayRange } from './index.js';
-
-describe('arrayRange', (): void => {
-  it('does not allow 0 values', (): void => {
-    expect(
-      () => arrayRange(0)
-    ).toThrow(/Expected non-zero, positive number as a range size/);
-  });
-
-  it('creates a range of the specified length', (): void => {
-    expect(
-      arrayRange(10)
-    ).toEqual([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
-  });
-
-  it('creates a range of the specified length, with offset', (): void => {
-    expect(
-      arrayRange(7, 3)
-    ).toEqual([3, 4, 5, 6, 7, 8, 9]);
-  });
-
-  perf('arrayRange (100 entries)', 1_000_000, [[100]], arrayRange);
-});

package/src/array/shuffle.spec.ts

@@ -1,39 +0,0 @@
-// Copyright 2017-2025 @polkadot/util authors & contributors
-// SPDX-License-Identifier: Apache-2.0
-
-/// <reference types="@polkadot/dev-test/globals.d.ts" />
-
-import { stringify } from '../stringify.js';
-import { perf } from '../test/index.js';
-import { arrayRange, arrayShuffle } from './index.js';
-
-const ptest = arrayRange(16284);
-
-describe('arrayShuffle', (): void => {
-  it('returns an empty array as-is', (): void => {
-    expect(
-      arrayShuffle([])
-    ).toEqual([]);
-  });
-
-  it('returns a single array as-is', (): void => {
-    expect(
-      arrayShuffle([100])
-    ).toEqual([100]);
-  });
-
-  it('shuffles an array', (): void => {
-    const inp = arrayRange(100);
-    const out = arrayShuffle(inp);
-
-    expect(inp).toHaveLength(out.length);
-    expect(
-      inp.filter((v) => !out.includes(v))
-    ).toEqual([]);
-    expect(
-      stringify(inp)
-    ).not.toEqual(stringify(out));
-  });
-
-  perf('arrayShuffle', 1000, [[ptest]], arrayShuffle);
-});

package/src/array/shuffle.ts

@@ -1,27 +0,0 @@
-// Copyright 2017-2025 @polkadot/util authors & contributors
-// SPDX-License-Identifier: Apache-2.0
-
-/**
- * @name arrayShuffle
- * @description Shuffles the input array (unlike sort, this is not done in-place)
- */
-export function arrayShuffle <T> (input: readonly T[]): T[] {
-  const result = input.slice();
-  let curr = result.length;
-
-  // noop for the single entry
-  if (curr === 1) {
-    return result;
-  }
-
-  while (curr !== 0) {
-    // ~~ is more performant than Math.floor
-    const rand = ~~(Math.random() * curr);
-
-    curr--;
-
-    [result[curr], result[rand]] = [result[rand], result[curr]];
-  }
-
-  return result;
-}

package/src/array/unzip.spec.ts

@@ -1,14 +0,0 @@
-// Copyright 2017-2025 @polkadot/util authors & contributors
-// SPDX-License-Identifier: Apache-2.0
-
-/// <reference types="@polkadot/dev-test/globals.d.ts" />
-
-import { arrayUnzip } from './index.js';
-
-describe('arrayUnzip', (): void => {
-  it('unzips entries', (): void => {
-    expect(
-      arrayUnzip([['a', 1], ['b', 2], ['c', 3]])
-    ).toEqual([['a', 'b', 'c'], [1, 2, 3]]);
-  });
-});

package/src/array/unzip.ts

@@ -1,18 +0,0 @@
-// Copyright 2017-2025 @polkadot/util authors & contributors
-// SPDX-License-Identifier: Apache-2.0
-
-/**
- * @name arrayUnzip
- * @description Splits a single [K, V][] into [K[], V[]]
- */
-export function arrayUnzip <K, V> (entries: readonly [K, V][]): [K[], V[]] {
-  const count = entries.length;
-  const keys = new Array<K>(count);
-  const values = new Array<V>(count);
-
-  for (let i = 0; i < count; i++) {
-    [keys[i], values[i]] = entries[i];
-  }
-
-  return [keys, values];
-}

package/src/array/zip.spec.ts

@@ -1,26 +0,0 @@
-// Copyright 2017-2025 @polkadot/util authors & contributors
-// SPDX-License-Identifier: Apache-2.0
-
-/// <reference types="@polkadot/dev-test/globals.d.ts" />
-
-import { arrayZip } from './index.js';
-
-describe('arrayZip', (): void => {
-  it('zips a simple one', (): void => {
-    expect(
-      arrayZip(['a', 'b', 'c'], [1, 2, 3])
-    ).toEqual([['a', 1], ['b', 2], ['c', 3]]);
-  });
-
-  it('zips where values > keys', (): void => {
-    expect(
-      arrayZip(['a', 'b', 'c'], [1, 2, 3, 4])
-    ).toEqual([['a', 1], ['b', 2], ['c', 3]]);
-  });
-
-  it('zips where values < keys', (): void => {
-    expect(
-      arrayZip(['a', 'b', 'c'], [1, 2])
-    ).toEqual([['a', 1], ['b', 2], ['c', undefined]]);
-  });
-});

package/src/array/zip.ts

@@ -1,17 +0,0 @@
-// Copyright 2017-2025 @polkadot/util authors & contributors
-// SPDX-License-Identifier: Apache-2.0
-
-/**
- * @name arrayZip
- * @description Combines 2 distinct key/value arrays into a single [K, V] array
- */
-export function arrayZip <K, V> (keys: readonly K[], values: readonly V[]): [K, V][] {
-  const count = keys.length;
-  const result = new Array<[K, V]>(count);
-
-  for (let i = 0; i < count; i++) {
-    result[i] = [keys[i], values[i]];
-  }
-
-  return result;
-}

package/src/assert.spec.ts

@@ -1,40 +0,0 @@
-// Copyright 2017-2025 @polkadot/util authors & contributors
-// SPDX-License-Identifier: Apache-2.0
-
-/// <reference types="@polkadot/dev-test/globals.d.ts" />
-
-import { assert, assertReturn } from './index.js';
-
-describe('assert', (): void => {
-  it('should not throw an error when test is true', (): void => {
-    assert(true, 'nothing should be thrown');
-  });
-
-  it('should throw an error when test is not true', (): void => {
-    expect(
-      () => assert(false, 'error thrown')
-    ).toThrow(/error thrown/);
-  });
-
-  it('should throw an error when message: () => string', (): void => {
-    expect(
-      () => assert(false, (): string => 'message from function')
-    ).toThrow(/message from function/);
-  });
-});
-
-describe('assertReturn', (): void => {
-  it('should not throw an error when result is true', (): void => {
-    expect(assertReturn(true, 'nothing should be thrown')).toEqual(true);
-  });
-
-  it('should not throw an error when result is false', (): void => {
-    expect(assertReturn(false, 'nothing should be thrown')).toEqual(false);
-  });
-
-  it('should throw an error when result is undefined', (): void => {
-    expect(
-      () => assertReturn(undefined, 'something thrown')
-    ).toThrow(/something thrown/);
-  });
-});

package/src/bi/helpers.ts

@@ -1,23 +0,0 @@
-// Copyright 2017-2025 @polkadot/util authors & contributors
-// SPDX-License-Identifier: Apache-2.0
-
-/** @internal */
-export function createCmp <T> (cmp: (a: T, b: T) => boolean): (...items: T[]) => T {
-  return (...items: T[]): T => {
-    const count = items.length;
-
-    if (count === 0) {
-      throw new Error('Must provide one or more arguments');
-    }
-
-    let result = items[0];
-
-    for (let i = 1; i < count; i++) {
-      if (cmp(items[i], result)) {
-        result = items[i];
-      }
-    }
-
-    return result;
-  };
-}

package/src/bi/max.spec.ts

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

package/src/bi/min.spec.ts

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

package/src/bi/min.ts

@@ -1,16 +0,0 @@
-// Copyright 2017-2025 @polkadot/util authors & contributors
-// SPDX-License-Identifier: Apache-2.0
-
-import { createCmp } from './helpers.js';
-
-/**
- * @name nMax
- * @summary Finds and returns the highest value in an array of bigint.
- */
-export const nMax = /*#__PURE__*/ createCmp<bigint>((a, b) => a > b);
-
-/**
- * @name nMin
- * @summary Finds and returns the lowest value in an array of bigint.
- */
-export const nMin = /*#__PURE__*/ createCmp<bigint>((a, b) => a < b);