@pezkuwi/util 14.0.1

package/README.md

@@ -0,0 +1,17 @@
+# @pezkuwi/util
+
+Various useful utility functions that are used across all projects in the [@pezkuwi](https://pezkuwi.js.org) namespace. It provides utility functions with additional safety checks, allowing not only for consistent coding, but also reducing the general boilerplate.
+
+## Usage
+
+Installation -
+
+```
+yarn add @pezkuwi/util
+```
+
+Functions can be imported directly from the package, e.g.
+
+```js
+import { isHex } from '@pezkuwi/util';
+```

package/package.json

@@ -0,0 +1,49 @@
+{
+  "author": "Jaco Greeff <jacogr@gmail.com>",
+  "bugs": "https://github.com/pezkuwichain/pezkuwi-common/issues",
+  "description": "A collection of useful utilities for @pezkuwi",
+  "engines": {
+    "node": ">=18"
+  },
+  "homepage": "https://github.com/pezkuwichain/pezkuwi-common/tree/master/packages/util#readme",
+  "license": "Apache-2.0",
+  "name": "@pezkuwi/util",
+  "repository": {
+    "directory": "packages/util",
+    "type": "git",
+    "url": "https://github.com/pezkuwichain/pezkuwi-common.git"
+  },
+  "sideEffects": [
+    "./packageDetect.js",
+    "./packageDetect.cjs"
+  ],
+  "type": "module",
+  "version": "14.0.1",
+  "main": "index.js",
+  "exports": {
+    "./hex/toU8a": {
+      "node": {
+        "require": "./cjs/hex/toU8aBuffer.js",
+        "default": "./hex/toU8aBuffer.js"
+      }
+    },
+    "./u8a/toHex": {
+      "node": {
+        "require": "./cjs/u8a/toHexBuffer.js",
+        "default": "./u8a/toHexBuffer.js"
+      }
+    }
+  },
+  "dependencies": {
+    "@pezkuwi/x-bigint": "14.0.1",
+    "@pezkuwi/x-global": "14.0.1",
+    "@pezkuwi/x-textdecoder": "14.0.1",
+    "@pezkuwi/x-textencoder": "14.0.1",
+    "@types/bn.js": "^5.1.6",
+    "bn.js": "^5.2.1",
+    "tslib": "^2.8.0"
+  },
+  "devDependencies": {
+    "@pezkuwi/x-randomvalues": "14.0.1"
+  }
+}

package/src/array/chunk.spec.ts

@@ -0,0 +1,29 @@
+// 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

@@ -0,0 +1,35 @@
+// 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

@@ -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 { 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/filter.ts

@@ -0,0 +1,24 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @name arrayFilter
+ * @summary Filters undefined and (optionally) null values from an array
+ * @description
+ * Returns a new array with all `undefined` values removed. Optionally, when `allowNulls = false`, it removes the `null` values as well
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { arrayFilter } from '@pezkuwi/util';
+ *
+ * arrayFilter([0, void 0, true, null, false, '']); // [0, true, null, false, '']
+ * arrayFilter([0, void 0, true, null, false, ''], false); // [0, true, false, '']
+ * ```
+ */
+export function arrayFilter <T = unknown> (array: readonly (T | null | undefined)[], allowNulls = true): T[] {
+  return array.filter((v): v is T =>
+    v !== undefined &&
+    (allowNulls || v !== null)
+  );
+}

package/src/array/flatten.spec.ts

@@ -0,0 +1,33 @@
+// 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

@@ -0,0 +1,51 @@
+// 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/index.ts

@@ -0,0 +1,14 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @summary Utility methods that operates on arrays
+ */
+
+export { arrayChunk } from './chunk.js';
+export { arrayFilter } from './filter.js';
+export { arrayFlatten } from './flatten.js';
+export { arrayRange } from './range.js';
+export { arrayShuffle } from './shuffle.js';
+export { arrayUnzip } from './unzip.js';
+export { arrayZip } from './zip.js';

package/src/array/range.spec.ts

@@ -0,0 +1,29 @@
+// 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/range.ts

@@ -0,0 +1,31 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @name arrayRange
+ * @summary Returns a range of numbers ith the size and the specified offset
+ * @description
+ * Returns a new array of numbers with the specific size. Optionally, when `startAt`, is provided, it generates the range to start at a specific value.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { arrayRange } from '@pezkuwi/util';
+ *
+ * arrayRange(5); // [0, 1, 2, 3, 4]
+ * arrayRange(3, 5); // [5, 6, 7]
+ * ```
+ */
+export function arrayRange (size: number, startAt = 0): number[] {
+  if (size <= 0) {
+    throw new Error('Expected non-zero, positive number as a range size');
+  }
+
+  const result = new Array<number>(size);
+
+  for (let i = 0; i < size; i++) {
+    result[i] = i + startAt;
+  }
+
+  return result;
+}

package/src/array/shuffle.spec.ts

@@ -0,0 +1,39 @@
+// 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

@@ -0,0 +1,27 @@
+// 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

@@ -0,0 +1,14 @@
+// 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

@@ -0,0 +1,18 @@
+// 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

@@ -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 { 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

@@ -0,0 +1,17 @@
+// 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

@@ -0,0 +1,40 @@
+// 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/assert.ts

@@ -0,0 +1,50 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { isFunction } from './is/function.js';
+
+type MessageFn = () => string;
+
+/**
+ * @name assert
+ * @summary Checks for a valid test, if not Error is thrown.
+ * @description
+ * Checks that `test` is a truthy value. If value is falsy (`null`, `undefined`, `false`, ...), it throws an Error with the supplied `message`. When `test` passes, `true` is returned.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * const { assert } from '@pezkuwi/util';
+ *
+ * assert(true, 'True should be true'); // passes
+ * assert(false, 'False should not be true'); // Error thrown
+ * assert(false, () => 'message'); // Error with 'message'
+ * ```
+ */
+export function assert (condition: unknown, message: string | MessageFn): asserts condition {
+  if (!condition) {
+    throw new Error(
+      isFunction(message)
+        ? message()
+        : message
+    );
+  }
+}
+
+/**
+ * @name assertReturn
+ * @description Returns when the value is not undefined/null, otherwise throws assertion error
+ */
+export function assertReturn <T> (value: T | undefined | null, message: string | MessageFn): T {
+  assert(value !== undefined && value !== null, message);
+
+  return value;
+}
+
+/**
+ * @name assertUnreachable
+ * @description An assertion helper that ensures all codepaths are followed
+ */
+export function assertUnreachable (x: never): never {
+  throw new Error(`This codepath should be unreachable. Unhandled input: ${x as unknown as string}`);
+}