@pezkuwi/util 14.0.22 → 14.0.23

package/src/array/filter.ts

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

package/src/bi/consts.ts

@@ -0,0 +1,112 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { BigInt } from '@pezkuwi/x-bigint';
+
+/**
+ * @name _0n
+ * @summary BigInt constant for 0.
+ */
+export const _0n = /*#__PURE__*/ BigInt(0);
+
+/**
+ * @name _1n
+ * @summary BigInt constant for 1.
+ */
+export const _1n = /*#__PURE__*/ BigInt(1);
+
+/**
+ * @name _2n
+ * @summary BigInt constant for 2.
+ */
+export const _2n = /*#__PURE__*/ BigInt(2);
+
+/**
+ * @name _3n
+ * @summary BigInt constant for 3.
+ */
+export const _3n = /*#__PURE__*/ BigInt(3);
+
+/**
+ * @name _4n
+ * @summary BigInt constant for 4.
+ */
+export const _4n = /*#__PURE__*/ BigInt(4);
+
+/**
+ * @name _5n
+ * @summary BigInt constant for 5.
+ */
+export const _5n = /*#__PURE__*/ BigInt(5);
+
+/**
+ * @name _6n
+ * @summary BigInt constant for 6.
+ */
+export const _6n = /*#__PURE__*/ BigInt(6);
+
+/**
+ * @name _7n
+ * @summary BigInt constant for 7.
+ */
+export const _7n = /*#__PURE__*/ BigInt(7);
+
+/**
+ * @name _8n
+ * @summary BigInt constant for 8.
+ */
+export const _8n = /*#__PURE__*/ BigInt(8);
+
+/**
+ * @name _9n
+ * @summary BigInt constant for 9.
+ */
+export const _9n = /*#__PURE__*/ BigInt(9);
+
+/**
+ * @name _10n
+ * @summary BigInt constant for 10.
+ */
+export const _10n = /*#__PURE__*/ BigInt(10);
+
+/**
+ * @name _100n
+ * @summary BigInt constant for 100.
+ */
+export const _100n = /*#__PURE__*/ BigInt(100);
+
+/**
+ * @name _1000n
+ * @summary BigInt constant for 1000.
+ */
+export const _1000n = /*#__PURE__*/ BigInt(1_000);
+
+/**
+ * @name _1Mn
+ * @summary BigInt constant for 1,000,000 (million).
+ */
+export const _1Mn = /*#__PURE__*/ BigInt(1_000_000);
+
+/**
+* @name _1Bn
+* @summary BigInt constant for 1,000,000,000 (billion).
+*/
+export const _1Bn = /*#__PURE__*/ BigInt(1_000_000_000);
+
+/**
+* @name _1Qn
+* @summary BigInt constant for 1,000,000,000,000,000,000 (quitillion).
+*/
+export const _1Qn = _1Bn * _1Bn;
+
+/**
+* @name _2pow53n
+* @summary BigInt constant for MAX_SAFE_INTEGER
+*/
+export const _2pow53n = /*#__PURE__*/ BigInt(Number.MAX_SAFE_INTEGER);
+
+/**
+ * @name _sqrt2pow53n
+ * @summary BigInt constant for Math.sqrt(MAX_SAFE_INTEGER)
+ */
+export const _sqrt2pow53n = /*#__PURE__*/ BigInt(94906265);

package/src/bi/helpers.ts

@@ -0,0 +1,23 @@
+// Copyright 2017-2025 @pezkuwi/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/index.ts

@@ -0,0 +1,16 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @summary Utility methods to convert to and from `bigint` objects
+ */
+
+// all named
+export { nMax, nMin } from './min.js';
+export { nSqrt } from './sqrt.js';
+export { nToBigInt } from './toBigInt.js';
+export { nToHex } from './toHex.js';
+export { nToU8a } from './toU8a.js';
+
+// all starred
+export * from './consts.js';

package/src/bi/max.spec.ts

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

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

@@ -0,0 +1,16 @@
+// Copyright 2017-2025 @pezkuwi/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);