@pezkuwi/util 14.0.6 → 14.0.7

package/src/array/range.spec.ts

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

package/src/bi/sqrt.spec.ts

@@ -1,59 +0,0 @@
-// Copyright 2017-2025 @pezkuwi/util authors & contributors
-// SPDX-License-Identifier: Apache-2.0
-
-/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
-
-import { BN } from '../bn/index.js';
-import { _sqrt2pow53n, nSqrt } from './index.js';
-
-// eslint-disable-next-line jest/no-export
-export const TESTS: [value: string | number | BN | bigint, expected: string | number][] = [
-  [0, 0],
-  [1, 1],
-  [4, 2],
-  [256 * 256, 256],
-  [Number.MAX_SAFE_INTEGER, 94906265],
-  [new BN(Number.MAX_SAFE_INTEGER).iaddn(256), 94906265],
-  [12345678n * 12345679n, 12345678],
-  // test cases below from https://github.com/Aisse-258/bigint-isqrt/blob/f5254b9750841959022461c1353437a07a08f501/test/sqrt-test.js
-  [
-    '54866395443885995655625',
-    '234235768925'
-  ],
-  [
-    '82120471531550314555681345949499512621827274120673745141541602816614526075010755373654280259022317599142038423759320355177481886719814621305828811322920076213800348341464996337890625',
-    '9062034624274524065844376014975805577107171799890766992670739972241112960081909332275390625'
-  ],
-  [
-    '2068290204957779940494571454815902632050207752627007664813877111611972735314294907791993008455381265730624848057015476004143868408297250386512042711005577373327434315310235583583151773358353534031397385969275475421659036494173765903706963544628565027679444680637920371210258368358706248446698622704138943704561842220533563976838506992543814273403403362954987589637283890281226038798503294069403370486523697009383229578343444337394508531937972775639593763364402389410142290440075517598007930025487176173228232153685095699851764630884360483051570513804913157899314303269924424908606245851172031453725690942288677622973423417902662711606364188470325930406288190754356367655606430407552275285889968860367977288564364154999338284288438279464648663835830140826171534470717958048887869721791862539529444820484648908879364324577951008050851801647916673254009490596379549192296404841454780884358889449367135382779230574781333008561195244620152128505091883408484094800737142399855337799331037607433934520934135669364954550499058123797911762228642423567268540444910163468496805547450495819213412636594319148417857753712526066272727725420886898680432958409892237191284583904066400736417812258327303739879128916456683685232170600928808798462776174857486589598776587550843543720784829419478239563366491666155716208452087857080883906200829769222868347286071365156305396955420561718593130305703074908891135467193627721682044757187980688062367562451981939375400543212890625',
-    '45478458691536369397924851088318871329614555665525810477032568598360481742967756704524034986984134271202405190906906195123751965012732122548540879928668891416468847696038707003466943811913626146981446753434347552196868717612248915137033581428310504778371173112125038060138252719589122657221314190626986951627417768579641354255445988772645883238873672997347648890137913979299598785628581961589739331483895853398160785485300758458294999124984266041998145956341386549681176624661615465976970855592467853824812945820721933491609237311130118125761849911376495970746282571994312288380577879004620824004760109618074670810797544446334767103935754106103208789391060008291027361311679876439695844637933763721093782805837690830230712890625'
-  ]
-];
-
-describe('nSqrt', (): void => {
-  it('fails on < 0 roots', (): void => {
-    expect(
-      () => nSqrt(-1n)
-    ).toThrow(/negative numbers is not supported/);
-  });
-
-  it('has the correct constant for sqrt(Number.MAX_SAFE_INTEGER)', (): void => {
-    expect(
-      BigInt(
-        ~~Math.sqrt(
-          Number.MAX_SAFE_INTEGER
-        )
-      ) === _sqrt2pow53n
-    ).toEqual(true);
-  });
-
-  describe('conversion tests', (): void => {
-    TESTS.forEach(([value, expected], i): void => {
-      it(`#${i}: calcs ${expected}`, (): void => {
-        expect(
-          nSqrt(value) === BigInt(expected)
-        ).toEqual(true);
-      });
-    });
-  });
-});

package/src/bi/sqrt.ts

@@ -1,43 +0,0 @@
-// Copyright 2017-2025 @pezkuwi/util authors & contributors
-// SPDX-License-Identifier: Apache-2.0
-
-import type { BN } from '../bn/index.js';
-import type { ToBigInt, ToBn } from '../types.js';
-
-import { BigInt } from '@pezkuwi/x-bigint';
-
-import { _0n, _1n, _2pow53n, _sqrt2pow53n } from './consts.js';
-import { nToBigInt } from './toBigInt.js';
-
-/**
- * @name nSqrt
- * @summary Calculates the integer square root of a bigint
- */
-export function nSqrt <ExtToBn extends ToBn | ToBigInt> (value: ExtToBn | BN | bigint | string | number | null): bigint {
-  const n = nToBigInt(value);
-
-  if (n < _0n) {
-    throw new Error('square root of negative numbers is not supported');
-  }
-
-  // https://stackoverflow.com/questions/53683995/javascript-big-integer-square-root/
-  // shortcut <= 2^53 - 1 to use the JS utils
-  if (n <= _2pow53n) {
-    // ~~ is more performant that Math.floor
-    return BigInt(~~Math.sqrt(Number(n)));
-  }
-
-  // Use sqrt(MAX_SAFE_INTEGER) as starting point. since we already know the
-  // output will be larger than this, we expect this to be a safe start
-  let x0 = _sqrt2pow53n;
-
-  while (true) {
-    const x1 = ((n / x0) + x0) >> _1n;
-
-    if (x0 === x1 || (x0 === (x1 - _1n))) {
-      return x0;
-    }
-
-    x0 = x1;
-  }
-}