@pezkuwi/util 14.0.1

package/src/hex/toU8a.ts

@@ -0,0 +1,68 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+const CHR = '0123456789abcdef';
+const U8 = new Uint8Array(256);
+const U16 = new Uint8Array(256 * 256);
+
+for (let i = 0, count = CHR.length; i < count; i++) {
+  U8[CHR[i].charCodeAt(0) | 0] = i | 0;
+
+  if (i > 9) {
+    U8[CHR[i].toUpperCase().charCodeAt(0) | 0] = i | 0;
+  }
+}
+
+for (let i = 0; i < 256; i++) {
+  const s = i << 8;
+
+  for (let j = 0; j < 256; j++) {
+    U16[s | j] = (U8[i] << 4) | U8[j];
+  }
+}
+
+/**
+ * @name hexToU8a
+ * @summary Creates a Uint8Array object from a hex string.
+ * @description
+ * `null` inputs returns an empty `Uint8Array` result. Hex input values return the actual bytes value converted to a Uint8Array. Anything that is not a hex string (including the `0x` prefix) throws an error.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { hexToU8a } from '@pezkuwi/util';
+ *
+ * hexToU8a('0x80001f'); // Uint8Array([0x80, 0x00, 0x1f])
+ * hexToU8a('0x80001f', 32); // Uint8Array([0x00, 0x80, 0x00, 0x1f])
+ * ```
+ */
+export function hexToU8a (value?: string | null, bitLength = -1): Uint8Array {
+  if (!value) {
+    return new Uint8Array();
+  }
+
+  let s = value.startsWith('0x')
+    ? 2
+    : 0;
+
+  const decLength = Math.ceil((value.length - s) / 2);
+  const endLength = Math.ceil(
+    bitLength === -1
+      ? decLength
+      : bitLength / 8
+  );
+  const result = new Uint8Array(endLength);
+  const offset = endLength > decLength
+    ? endLength - decLength
+    : 0;
+
+  for (let i = offset; i < endLength; i++, s += 2) {
+    // The big factor here is actually the string lookups. If we do
+    // HEX_TO_U16[value.substring()] we get an 10x slowdown. In the
+    // same vein using charCodeAt (as opposed to value[s] or value.charAt(s)) is
+    // also the faster operation by at least 2x with the character map above
+    result[i] = U16[(value.charCodeAt(s) << 8) | value.charCodeAt(s + 1)];
+  }
+
+  return result;
+}

package/src/hex/toU8aBuffer.spec.ts

@@ -0,0 +1,38 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+import { hexToU8a } from './toU8aBuffer.js';
+
+describe('hexToU8a', (): void => {
+  it('returns an empty Uint8Array when null provided', (): void => {
+    expect(
+      hexToU8a(null)
+    ).toHaveLength(0);
+  });
+
+  it('returns a Uint8Array with the correct values', (): void => {
+    expect(
+      hexToU8a('0x80000a')
+    ).toEqual(
+      new Uint8Array([128, 0, 10])
+    );
+  });
+
+  it('returns a Uint8Array with the correct values (bitLength > provided)', (): void => {
+    expect(
+      hexToU8a('0x80000A', 64)
+    ).toEqual(
+      new Uint8Array([0, 0, 0, 0, 0, 128, 0, 10])
+    );
+  });
+
+  it('returns a Uint8Array with the correct values (bitLength < provided)', (): void => {
+    expect(
+      hexToU8a('0x80000a', 16)
+    ).toEqual(
+      new Uint8Array([128, 0])
+    );
+  });
+});

package/src/hex/toU8aBuffer.ts

@@ -0,0 +1,52 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @name hexToU8a
+ * @summary Creates a Uint8Array object from a hex string.
+ * @description
+ * `null` inputs returns an empty `Uint8Array` result. Hex input values return the actual bytes value converted to a Uint8Array. Anything that is not a hex string (including the `0x` prefix) throws an error.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { hexToU8a } from '@pezkuwi/util';
+ *
+ * hexToU8a('0x80001f'); // Uint8Array([0x80, 0x00, 0x1f])
+ * hexToU8a('0x80001f', 32); // Uint8Array([0x00, 0x80, 0x00, 0x1f])
+ * ```
+ */
+export function hexToU8a (_value?: string | null, bitLength = -1): Uint8Array {
+  if (!_value) {
+    return new Uint8Array();
+  }
+
+  const value = _value.startsWith('0x')
+    ? _value.substring(2)
+    : _value;
+  const buf = Buffer.from(value, 'hex');
+  const valLength = value.length / 2;
+  const resultLength = Math.ceil(
+    bitLength === -1
+      ? valLength
+      : bitLength / 8
+  );
+
+  if (resultLength === valLength) {
+    return Uint8Array.from(buf);
+  }
+
+  const offset = resultLength > valLength
+    ? resultLength - valLength
+    : 0;
+
+  if (offset) {
+    const u8a = new Uint8Array(resultLength);
+
+    u8a.set(buf, offset);
+
+    return u8a;
+  }
+
+  return Uint8Array.from(buf.subarray(0, resultLength));
+}

package/src/index.spec.ts

@@ -0,0 +1,12 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+import { assert } from './index.js';
+
+describe('index', (): void => {
+  it('exports ok', (): void => {
+    expect(assert).toBeDefined();
+  });
+});

package/src/index.ts

@@ -0,0 +1,6 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import './packageDetect.js';
+
+export * from './bundle.js';

package/src/is/array.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 { isArray } from './index.js';
+
+describe('isArray', (): void => {
+  it('is false on no value', (): void => {
+    expect(isArray()).toEqual(false);
+  });
+
+  it('is false on non-array', (): void => {
+    expect(isArray(123)).toEqual(false);
+  });
+
+  it('is true when Array is found', (): void => {
+    expect(isArray([1, 2, 3])).toEqual(true);
+  });
+});

package/src/is/array.ts

@@ -0,0 +1,10 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @name isArray
+ * @summary Tests for a Array instance.
+ */
+export function isArray <T> (value?: unknown): value is T[] {
+  return Array.isArray(value);
+}

package/src/is/ascii.spec.ts

@@ -0,0 +1,49 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+import { stringToU8a } from '../string/index.js';
+import { perf } from '../test/index.js';
+import { isAscii } from './index.js';
+
+describe('isAscii', (): void => {
+  it('returns true for an ASCII string', (): void => {
+    expect(isAscii('Hello World! Testing')).toEqual(true);
+  });
+
+  it('returns false for an ASCII string (with formatters)', (): void => {
+    expect(isAscii('Hello\tWorld!\n\rTesting')).toEqual(false);
+  });
+
+  it('returns false on an non-ascii string', (): void => {
+    expect(isAscii('你好，世界')).toEqual(false);
+  });
+
+  it('returns true for ASCII bytes', (): void => {
+    expect(isAscii(stringToU8a('Hello World! Testing'))).toEqual(true);
+  });
+
+  it('returns true for empty string inputs', (): void => {
+    expect(isAscii('')).toEqual(true);
+  });
+
+  it('returns true for empty U8a inputs', (): void => {
+    expect(isAscii(new Uint8Array())).toEqual(true);
+  });
+
+  it('returns false for empty undefined inputs', (): void => {
+    expect(isAscii()).toEqual(false);
+  });
+
+  it('returns false for non-printable characters', (): void => {
+    expect(isAscii(new Uint8Array([5]))).toEqual(false);
+  });
+
+  it('returns false for hex input, non-ascii', (): void => {
+    expect(isAscii('0x010203')).toEqual(false);
+  });
+
+  perf('isAscii (str)', 2_000_000, [['Hello World! Testing']], isAscii);
+  perf('isAscii (u8a)', 200_000, [[[stringToU8a('Hello World! Testing')]]], isAscii);
+});

package/src/is/ascii.ts

@@ -0,0 +1,52 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { AnyString, U8aLike } from '../types.js';
+
+import { u8aToU8a } from '../u8a/toU8a.js';
+import { isHex } from './hex.js';
+import { isString } from './string.js';
+
+/** @internal */
+function isAsciiStr (str: AnyString): boolean {
+  for (let i = 0, count = str.length; i < count; i++) {
+    const b = str.charCodeAt(i);
+
+    // check is inlined here, it is faster than making a call
+    if (b < 32 || b > 126) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/** @internal */
+function isAsciiBytes (u8a: Uint8Array | number[]): boolean {
+  for (let i = 0, count = u8a.length; i < count; i++) {
+    const b = u8a[i] | 0;
+
+    // check is inlined here, it is faster than making a call
+    if (b < 32 || b > 126) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * @name isAscii
+ * @summary Tests if the input is printable ASCII
+ * @description
+ * Checks to see if the input string or Uint8Array is printable ASCII, 32-127 + formatters
+ */
+export function isAscii (value?: U8aLike | null): boolean {
+  return isString(value)
+    ? isHex(value)
+      ? isAsciiBytes(u8aToU8a(value))
+      : isAsciiStr(value)
+    : value
+      ? isAsciiBytes(value)
+      : false;
+}

package/src/is/bigInt.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 { isBigInt } from './index.js';
+
+describe('isBigInt', (): void => {
+  it('returns true with a ...n value', (): void => {
+    expect(
+      isBigInt(123456n)
+    ).toEqual(true);
+  });
+
+  it('returns true with a BigInt(...) value', (): void => {
+    expect(
+      isBigInt(BigInt(123456))
+    ).toEqual(true);
+  });
+
+  it('returns false on non-BigInt values', (): void => {
+    expect(
+      isBigInt(0)
+    ).toEqual(false);
+  });
+});

package/src/is/bigInt.ts

@@ -0,0 +1,20 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @name isBigInt
+ * @summary Tests for a `BigInt` object instance.
+ * @description
+ * Checks to see if the input object is an instance of `BigInt`
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { isBigInt } from '@pezkuwi/util';
+ *
+ * console.log('isBigInt', isBigInt(123_456n)); // => true
+ * ```
+ */
+export function isBigInt (value: unknown): value is bigint {
+  return typeof value === 'bigint';
+}

package/src/is/bn.spec.ts

@@ -0,0 +1,21 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+import { BN } from '../bn/index.js';
+import { isBn } from './index.js';
+
+describe('isBN', (): void => {
+  it('returns true when a BN value', (): void => {
+    expect(
+      isBn(new BN(123))
+    ).toEqual(true);
+  });
+
+  it('returns false on non-BN values', (): void => {
+    expect(
+      isBn(0)
+    ).toEqual(false);
+  });
+});

package/src/is/bn.ts

@@ -0,0 +1,23 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { BN } from '../bn/bn.js';
+
+/**
+ * @name isBn
+ * @summary Tests for a `BN` object instance.
+ * @description
+ * Checks to see if the input object is an instance of `BN` (bn.js).
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import BN from 'bn.js';
+ * import { isBn } from '@pezkuwi/util';
+ *
+ * console.log('isBn', isBn(new BN(1))); // => true
+ * ```
+ */
+export function isBn (value: unknown): value is BN {
+  return BN.isBN(value);
+}

package/src/is/boolean.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 { isBoolean } from './index.js';
+
+describe('isBoolean', (): void => {
+  it('returns true on false', (): void => {
+    expect(
+      isBoolean(false)
+    ).toEqual(true);
+  });
+
+  it('returns true on true', (): void => {
+    expect(
+      isBoolean(true)
+    ).toEqual(true);
+  });
+
+  it('returns false on invalid booleans', (): void => {
+    expect(
+      isBoolean('notABool')
+    ).toEqual(false);
+  });
+});

package/src/is/boolean.ts

@@ -0,0 +1,20 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @name isBoolean
+ * @summary Tests for a boolean value.
+ * @description
+ * Checks to see if the input value is a JavaScript boolean.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { isBoolean } from '@pezkuwi/util';
+ *
+ * isBoolean(false); // => true
+ * ```
+ */
+export function isBoolean (value: unknown): value is boolean {
+  return typeof value === 'boolean';
+}

package/src/is/buffer.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 { isBuffer } from './index.js';
+
+describe('isBuffer', (): void => {
+  it('returns true when a Buffer value', (): void => {
+    expect(
+      isBuffer(Buffer.from([]))
+    ).toEqual(true);
+  });
+
+  it('returns false on non-Buffer values (number)', (): void => {
+    expect(
+      isBuffer(123)
+    ).toEqual(false);
+  });
+
+  it('returns false on non-Buffer values (null)', (): void => {
+    expect(
+      isBuffer(null)
+    ).toEqual(false);
+  });
+});

package/src/is/buffer.ts

@@ -0,0 +1,28 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { BufferClass, BufferObject } from '../types.js';
+
+import { xglobal } from '@pezkuwi/x-global';
+
+import { hasBuffer } from '../has.js';
+import { isFunction } from './function.js';
+
+/**
+ * @name isBuffer
+ * @summary Tests for a `Buffer` object instance.
+ * @description
+ * Checks to see if the input object is an instance of `Buffer`.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { isBuffer } from '@pezkuwi/util';
+ *
+ * console.log('isBuffer', isBuffer(Buffer.from([]))); // => true
+ * ```
+ */
+export function isBuffer <T = BufferObject> (value: unknown): value is T {
+  // we do check a function first, since it is slightly faster than isBuffer itself
+  return hasBuffer && !!value && isFunction((value as unknown as BufferObject).readDoubleLE) && (xglobal.Buffer as unknown as BufferClass).isBuffer(value);
+}

package/src/is/childClass.spec.ts

@@ -0,0 +1,36 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+import { BN } from '../bn/index.js';
+import { isChildClass } from './index.js';
+
+describe('isChildClass', (): void => {
+  it('returns true when a Child value', (): void => {
+    expect(
+      isChildClass(BN, class Test extends BN {})
+    ).toEqual(true);
+  });
+
+  it('returns false on non-Child values', (): void => {
+    expect(
+      isChildClass(BN, Uint8Array)
+    ).toEqual(false);
+  });
+
+  it('returns false on undefined', (): void => {
+    expect(
+      isChildClass(BN)
+    ).toEqual(false);
+  });
+
+  it('does TS magic, determining type', (): void => {
+    const T = (class extends BN {}) as unknown;
+
+    expect(
+      isChildClass(BN, T) &&
+      new T(12345).toNumber()
+    ).toEqual(12345);
+  });
+});

package/src/is/childClass.ts

@@ -0,0 +1,29 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Class } from '../types.js';
+
+import { isClass } from './class.js';
+
+/**
+ * @name isChildClass
+ * @summary Tests if the child extends the parent Class
+ * @description
+ * Checks to see if the child Class extends the parent Class
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { isChildClass } from '@pezkuwi/util';
+ *
+ * console.log('isChildClass', isChildClass(BN, BN); // => true
+ * console.log('isChildClass', isChildClass(BN, Uint8Array); // => false
+ * ```
+ */
+export function isChildClass <P extends Class> (Parent: P, Child?: unknown): Child is P {
+  // https://stackoverflow.com/questions/30993434/check-if-a-constructor-inherits-another-in-es6/30993664
+  return isClass(Child) && isClass(Parent)
+    // eslint-disable-next-line no-prototype-builtins
+    ? Parent === Child || Parent.isPrototypeOf(Child)
+    : false;
+}

package/src/is/class.spec.ts

@@ -0,0 +1,37 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+import { BN } from '../bn/index.js';
+import { isClass } from './index.js';
+
+describe('isClass', (): void => {
+  it('returns false on a pure object', (): void => {
+    expect(isClass({})).toEqual(false);
+  });
+
+  it('returns false on instance values', (): void => {
+    expect(
+      isClass(new BN(1))
+    ).toEqual(false);
+  });
+
+  it('returns true when a class value', (): void => {
+    expect(
+      isClass(BN)
+    ).toEqual(true);
+  });
+
+  it('returns true on extends', (): void => {
+    expect(
+      isClass(class Test extends BN {})
+    ).toEqual(true);
+  });
+
+  it('returns true on built-ins', (): void => {
+    expect(
+      isClass(Uint8Array)
+    ).toEqual(true);
+  });
+});

package/src/is/class.ts

@@ -0,0 +1,12 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Class } from '../types.js';
+
+import { isOnFunction } from './helpers.js';
+
+/**
+ * @name isClass
+ * Tests if the supplied argument is a Class
+ */
+export const isClass: <T extends Class> (value?: unknown) => value is T = /*#__PURE__*/ isOnFunction('isPrototypeOf', 'hasOwnProperty');