@pezkuwi/util 14.0.7 → 14.0.10

package/src/is/riscv.spec.ts

@@ -0,0 +1,36 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { isRiscV } from './index.js';
+
+describe('isRiscV', (): void => {
+  it('is false on non-elf/non-pvm header', (): void => {
+    expect(isRiscV(new Uint8Array([0, 97, 115, 109, 1, 2, 3]))).toEqual(false);
+  });
+
+  it('is false on partial-elf/pvm header', (): void => {
+    expect(isRiscV(new Uint8Array([0x7f, 0x45, 0x4c]))).toEqual(false);
+  });
+
+  it('is false on empty byte before elf/pvm header', (): void => {
+    expect(
+      isRiscV(
+        new Uint8Array([0x00, 0x7f, 0x45, 0x4c, 0x46, 0xff, 0x00, 0x42, 0x23])
+      )
+    ).toEqual(false);
+  });
+
+  it('is true when a elf header is found', (): void => {
+    expect(
+      isRiscV(new Uint8Array([0x7f, 0x45, 0x4c, 0x46, 0xff, 0x00, 0x42, 0x23]))
+    ).toEqual(true);
+  });
+
+  it('is true when a pvm header is found', (): void => {
+    expect(
+      isRiscV(new Uint8Array([0x50, 0x56, 0x4d, 0x00, 0xff, 0x00, 0x42, 0x23]))
+    ).toEqual(true);
+  });
+});

package/src/is/riscv.ts

@@ -0,0 +1,27 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { u8aEq } from '../u8a/eq.js';
+import { isU8a } from './u8a.js';
+
+// general elf header
+const ELF_MAGIC = new Uint8Array([0x7f, 0x45, 0x4c, 0x46]); // ELF magic bytes: 0x7f, 'E', 'L', 'F'
+
+// contract-specific PVM header
+const PVM_MAGIC = new Uint8Array([0x50, 0x56, 0x4d, 0x00]); // 'P', 'V', 'M', 0x00
+
+/**
+ * @name isRiscV
+ * @summary Tests if the input has a RISC-V header
+ * @description
+ * Checks to see if the input Uint8Array contains a valid RISC-V header
+ */
+export function isRiscV (bytes: unknown): bytes is Uint8Array {
+  if (isU8a(bytes)) {
+    const start = bytes.subarray(0, 4);
+
+    return u8aEq(start, PVM_MAGIC) || u8aEq(start, ELF_MAGIC);
+  }
+
+  return false;
+}

package/src/is/string.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 { isString } from './index.js';
+
+describe('isString', (): void => {
+  it('returns true on valid strings', (): void => {
+    expect(
+      isString('123')
+    ).toEqual(true);
+  });
+
+  it('returns true on empty strings', (): void => {
+    expect(
+      isString('')
+    ).toEqual(true);
+  });
+
+  it('returns true on String object', (): void => {
+    expect(
+      isString(String('foo'))
+    ).toEqual(true);
+  });
+
+  it('returns false on invalid numbers', (): void => {
+    expect(
+      isString(2)
+    ).toEqual(false);
+  });
+});

package/src/is/string.ts

@@ -0,0 +1,22 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { AnyString } from '../types.js';
+
+/**
+ * @name isString
+ * @summary Tests for a string.
+ * @description
+ * Checks to see if the input value is a JavaScript string.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { isString } from '@pezkuwi/util';
+ *
+ * console.log('isString', isString('test')); // => true
+ * ```
+ */
+export function isString (value: unknown): value is AnyString {
+  return typeof value === 'string' || value instanceof String;
+}

package/src/is/testChain.spec.ts

@@ -0,0 +1,25 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { isTestChain } from './index.js';
+
+describe('isTestChain', (): void => {
+  it('enables test environment when chain specification matches text of dev or loc(al)', (): void => {
+    const validTestModeChainSpecsWithDev = ['Development'];
+    const validTestModeChainSpecsWithLoc = ['Local Testnet'];
+
+    validTestModeChainSpecsWithDev.concat(validTestModeChainSpecsWithLoc).forEach((s): void => {
+      expect(isTestChain(s)).toEqual(true);
+    });
+  });
+
+  it('disables keyring test mode when chain specification is not a test mode or undefined or number type', (): void => {
+    const invalidTestModeChainSpecs = ['dev', 'local', 'development', 'PoC-1 Testnet', 'Staging Testnet', 'future PoC-2 Testnet', 'a pocadot?', undefined];
+
+    invalidTestModeChainSpecs.forEach((s): void => {
+      expect(isTestChain(s)).toEqual(false);
+    });
+  });
+});

package/src/is/testChain.ts

@@ -0,0 +1,12 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+const REGEX_DEV = /(Development|Local Testnet)$/;
+
+export function isTestChain (chain?: string | null): boolean {
+  if (!chain) {
+    return false;
+  }
+
+  return !!REGEX_DEV.test(chain.toString());
+}

package/src/is/toBigInt.spec.ts

@@ -0,0 +1,22 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { isToBigInt } from './index.js';
+
+describe('isToBigInt', (): void => {
+  it('is false on no value', (): void => {
+    expect(isToBigInt()).toEqual(false);
+  });
+
+  it('is false on non-compact value', (): void => {
+    expect(isToBigInt(123)).toEqual(false);
+  });
+
+  it('is true when compact-like signature is found', (): void => {
+    expect(isToBigInt({
+      toBigInt: () => BigInt(1)
+    })).toEqual(true);
+  });
+});

package/src/is/toBigInt.ts

@@ -0,0 +1,8 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { ToBigInt } from '../types.js';
+
+import { isOn } from './helpers.js';
+
+export const isToBigInt = /*#__PURE__*/ isOn<ToBigInt>('toBigInt');

package/src/is/toBn.spec.ts

@@ -0,0 +1,25 @@
+// 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.js';
+
+import { isToBn } from './index.js';
+
+describe('isToBn', (): void => {
+  it('is false on no value', (): void => {
+    expect(isToBn()).toEqual(false);
+  });
+
+  it('is false on non-compact value', (): void => {
+    expect(isToBn(123)).toEqual(false);
+  });
+
+  it('is true when compact-like signature is found', (): void => {
+    expect(isToBn({
+      toBigInt: () => BigInt(1),
+      toBn: () => new BN(1)
+    })).toEqual(true);
+  });
+});

package/src/is/toBn.ts

@@ -0,0 +1,8 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { ToBn } from '../types.js';
+
+import { isOn } from './helpers.js';
+
+export const isToBn = /*#__PURE__*/ isOn<ToBn>('toBn');

package/src/is/u8a.spec.ts

@@ -0,0 +1,42 @@
+// 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 { isU8a } from './index.js';
+
+describe('isU8a', (): void => {
+  it('returns false on undefined values', (): void => {
+    expect(
+      isU8a()
+    ).toEqual(false);
+  });
+
+  it('returns false on null values', (): void => {
+    expect(
+      isU8a(null)
+    ).toEqual(false);
+  });
+
+  it('returns false on Array values', (): void => {
+    expect(
+      isU8a([1, 2, 3])
+    ).toEqual(false);
+  });
+
+  it('returns true on Buffer values', (): void => {
+    // under Node, Buffer implements Uint8Array
+    expect(
+      isU8a(Buffer.from([1, 2, 3]))
+    ).toEqual(true);
+  });
+
+  it('returns true on Uint8Array values', (): void => {
+    expect(
+      isU8a(new Uint8Array())
+    ).toEqual(true);
+  });
+
+  perf('isU8a', 2_000_000, [[new Uint8Array()]], isU8a);
+});

package/src/is/u8a.ts

@@ -0,0 +1,25 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @name isU8a
+ * @summary Tests for a `Uint8Array` object instance.
+ * @description
+ * Checks to see if the input object is an instance of `Uint8Array`.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { isUint8Array } from '@pezkuwi/util';
+ *
+ * console.log('isU8a', isU8a([])); // => false
+ * ```
+ */
+export function isU8a (value?: unknown): value is Uint8Array {
+  // here we defer the instanceof check which is actually slightly
+  // slower than just checking the constrctor (direct instances)
+  return (
+    ((value && (value as Uint8Array).constructor) === Uint8Array) ||
+    value instanceof Uint8Array
+  );
+}

package/src/is/undefined.spec.ts

@@ -0,0 +1,23 @@
+// 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 { isUndefined } from './index.js';
+
+describe('isUndefined', (): void => {
+  it('returns true on undefined values', (): void => {
+    expect(
+      isUndefined()
+    ).toEqual(true);
+  });
+
+  it('returns false on defined values', (): void => {
+    expect(
+      isUndefined(null)
+    ).toEqual(false);
+  });
+
+  perf('isUndefined', 10_000_000, [[null]], isUndefined);
+});

package/src/is/undefined.ts

@@ -0,0 +1,21 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @name isUndefined
+ * @summary Tests for a `undefined` values.
+ * @description
+ * Checks to see if the input value is `undefined`.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { isUndefined } from '@pezkuwi/util';
+ *
+ * console.log('isUndefined', isUndefined(void(0))); // => true
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function isUndefined (value?: unknown): value is undefined {
+  return value === undefined;
+}

package/src/is/utf8.spec.ts

@@ -0,0 +1,42 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { isUtf8 } from './index.js';
+
+describe('isUtf8', (): void => {
+  it('returns true for an ASCII string', (): void => {
+    expect(isUtf8('Hello\tWorld!\n\rTesting')).toEqual(true);
+  });
+
+  it('returns true for ASCII bytes', (): void => {
+    expect(isUtf8(new Uint8Array([0x31, 0x32, 0x20, 10]))).toEqual(true);
+  });
+
+  it('returns true for empty string inputs', (): void => {
+    expect(isUtf8('')).toEqual(true);
+  });
+
+  it('returns true for empty U8a inputs', (): void => {
+    expect(isUtf8(new Uint8Array())).toEqual(true);
+  });
+
+  it('returns false for empty undefined inputs', (): void => {
+    expect(isUtf8()).toEqual(false);
+  });
+
+  it('is valid for ru', (): void => {
+    expect(isUtf8('Приветствую, ми')).toEqual(true);
+  });
+
+  it('is valid for zh', (): void => {
+    expect(isUtf8('你好')).toEqual(true);
+  });
+
+  it('is invalid for something random', (): void => {
+    expect(isUtf8('0x7f07b1f87709608bee603bbc79a0dfc29cd315c1351a83aa31adf7458d7d3003')).toEqual(false);
+    expect(isUtf8('0xc9ec51351beec59b52db06b3dd4685004013035df080358c319553ced597ca05')).toEqual(false);
+    expect(isUtf8('0xd12cef06e90a05b63737d542aaee1389ff9f5c25e461b362180f025c3b2d5635')).toEqual(false);
+  });
+});

package/src/is/utf8.ts

@@ -0,0 +1,207 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+// Adapted from https://github.com/JulienPalard/is_utf8/blob/master/is_utf8.c
+
+import { u8aToU8a } from '../u8a/toU8a.js';
+import { isString } from './string.js';
+
+/**
+ * @name isUtf8
+ * @summary Tests if the input is valid Utf8
+ * @description
+ * Checks to see if the input string or Uint8Array is valid Utf8
+ */
+export function isUtf8 (value?: number[] | Uint8Array | string | null): boolean {
+  if (!value) {
+    return isString(value);
+  }
+
+  const u8a = u8aToU8a(value);
+  const len = u8a.length;
+  let i = 0;
+
+  while (i < len) {
+    if (u8a[i] <= 0x7F) /* 00..7F */ {
+      i += 1;
+    } else if (u8a[i] >= 0xC2 && u8a[i] <= 0xDF) /* C2..DF 80..BF */ {
+      if (i + 1 < len) /* Expect a 2nd byte */ {
+        if (u8a[i + 1] < 0x80 || u8a[i + 1] > 0xBF) {
+          // *message = "After a first byte between C2 and DF, expecting a 2nd byte between 80 and BF";
+          // *faulty_bytes = 2;
+          return false;
+        }
+      } else {
+        // *message = "After a first byte between C2 and DF, expecting a 2nd byte.";
+        // *faulty_bytes = 1;
+        return false;
+      }
+
+      i += 2;
+    } else if (u8a[i] === 0xE0) /* E0 A0..BF 80..BF */ {
+      if (i + 2 < len) /* Expect a 2nd and 3rd byte */ {
+        if (u8a[i + 1] < 0xA0 || u8a[i + 1] > 0xBF) {
+          // *message = "After a first byte of E0, expecting a 2nd byte between A0 and BF.";
+          // *faulty_bytes = 2;
+          return false;
+        }
+
+        if (u8a[i + 2] < 0x80 || u8a[i + 2] > 0xBF) {
+          // *message = "After a first byte of E0, expecting a 3nd byte between 80 and BF.";
+          // *faulty_bytes = 3;
+          return false;
+        }
+      } else {
+        // *message = "After a first byte of E0, expecting two following bytes.";
+        // *faulty_bytes = 1;
+        return false;
+      }
+
+      i += 3;
+    } else if (u8a[i] >= 0xE1 && u8a[i] <= 0xEC) /* E1..EC 80..BF 80..BF */ {
+      if (i + 2 < len) /* Expect a 2nd and 3rd byte */ {
+        if (u8a[i + 1] < 0x80 || u8a[i + 1] > 0xBF) {
+          // *message = "After a first byte between E1 and EC, expecting the 2nd byte between 80 and BF.";
+          // *faulty_bytes = 2;
+          return false;
+        }
+
+        if (u8a[i + 2] < 0x80 || u8a[i + 2] > 0xBF) {
+          // *message = "After a first byte between E1 and EC, expecting the 3rd byte between 80 and BF.";
+          // *faulty_bytes = 3;
+          return false;
+        }
+      } else {
+        // *message = "After a first byte between E1 and EC, expecting two following bytes.";
+        // *faulty_bytes = 1;
+        return false;
+      }
+
+      i += 3;
+    } else if (u8a[i] === 0xED) /* ED 80..9F 80..BF */ {
+      if (i + 2 < len) /* Expect a 2nd and 3rd byte */ {
+        if (u8a[i + 1] < 0x80 || u8a[i + 1] > 0x9F) {
+          // *message = "After a first byte of ED, expecting 2nd byte between 80 and 9F.";
+          // *faulty_bytes = 2;
+          return false;
+        }
+
+        if (u8a[i + 2] < 0x80 || u8a[i + 2] > 0xBF) {
+          // *message = "After a first byte of ED, expecting 3rd byte between 80 and BF.";
+          // *faulty_bytes = 3;
+          return false;
+        }
+      } else {
+        // *message = "After a first byte of ED, expecting two following bytes.";
+        // *faulty_bytes = 1;
+        return false;
+      }
+
+      i += 3;
+    } else if (u8a[i] >= 0xEE && u8a[i] <= 0xEF) /* EE..EF 80..BF 80..BF */ {
+      if (i + 2 < len) /* Expect a 2nd and 3rd byte */ {
+        if (u8a[i + 1] < 0x80 || u8a[i + 1] > 0xBF) {
+          // *message = "After a first byte between EE and EF, expecting 2nd byte between 80 and BF.";
+          // *faulty_bytes = 2;
+          return false;
+        }
+
+        if (u8a[i + 2] < 0x80 || u8a[i + 2] > 0xBF) {
+          // *message = "After a first byte between EE and EF, expecting 3rd byte between 80 and BF.";
+          // *faulty_bytes = 3;
+          return false;
+        }
+      } else {
+        // *message = "After a first byte between EE and EF, two following bytes.";
+        // *faulty_bytes = 1;
+        return false;
+      }
+
+      i += 3;
+    } else if (u8a[i] === 0xF0) /* F0 90..BF 80..BF 80..BF */ {
+      if (i + 3 < len) /* Expect a 2nd, 3rd 3th byte */ {
+        if (u8a[i + 1] < 0x90 || u8a[i + 1] > 0xBF) {
+          // *message = "After a first byte of F0, expecting 2nd byte between 90 and BF.";
+          // *faulty_bytes = 2;
+          return false;
+        }
+
+        if (u8a[i + 2] < 0x80 || u8a[i + 2] > 0xBF) {
+          // *message = "After a first byte of F0, expecting 3rd byte between 80 and BF.";
+          // *faulty_bytes = 3;
+          return false;
+        }
+
+        if (u8a[i + 3] < 0x80 || u8a[i + 3] > 0xBF) {
+          // *message = "After a first byte of F0, expecting 4th byte between 80 and BF.";
+          // *faulty_bytes = 4;
+          return false;
+        }
+      } else {
+        // *message = "After a first byte of F0, expecting three following bytes.";
+        // *faulty_bytes = 1;
+        return false;
+      }
+
+      i += 4;
+    } else if (u8a[i] >= 0xF1 && u8a[i] <= 0xF3) /* F1..F3 80..BF 80..BF 80..BF */ {
+      if (i + 3 < len) /* Expect a 2nd, 3rd 3th byte */ {
+        if (u8a[i + 1] < 0x80 || u8a[i + 1] > 0xBF) {
+          // *message = "After a first byte of F1, F2, or F3, expecting a 2nd byte between 80 and BF.";
+          // *faulty_bytes = 2;
+          return false;
+        }
+
+        if (u8a[i + 2] < 0x80 || u8a[i + 2] > 0xBF) {
+          // *message = "After a first byte of F1, F2, or F3, expecting a 3rd byte between 80 and BF.";
+          // *faulty_bytes = 3;
+          return false;
+        }
+
+        if (u8a[i + 3] < 0x80 || u8a[i + 3] > 0xBF) {
+          // *message = "After a first byte of F1, F2, or F3, expecting a 4th byte between 80 and BF.";
+          // *faulty_bytes = 4;
+          return false;
+        }
+      } else {
+        // *message = "After a first byte of F1, F2, or F3, expecting three following bytes.";
+        // *faulty_bytes = 1;
+        return false;
+      }
+
+      i += 4;
+    } else if (u8a[i] === 0xF4) /* F4 80..8F 80..BF 80..BF */ {
+      if (i + 3 < len) /* Expect a 2nd, 3rd 3th byte */ {
+        if (u8a[i + 1] < 0x80 || u8a[i + 1] > 0x8F) {
+          // *message = "After a first byte of F4, expecting 2nd byte between 80 and 8F.";
+          // *faulty_bytes = 2;
+          return false;
+        }
+
+        if (u8a[i + 2] < 0x80 || u8a[i + 2] > 0xBF) {
+          // *message = "After a first byte of F4, expecting 3rd byte between 80 and BF.";
+          // *faulty_bytes = 3;
+          return false;
+        }
+
+        if (u8a[i + 3] < 0x80 || u8a[i + 3] > 0xBF) {
+          // *message = "After a first byte of F4, expecting 4th byte between 80 and BF.";
+          // *faulty_bytes = 4;
+          return false;
+        }
+      } else {
+        // *message = "After a first byte of F4, expecting three following bytes.";
+        // *faulty_bytes = 1;
+        return false;
+      }
+
+      i += 4;
+    } else {
+      // *message = "Expecting bytes in the following ranges: 00..7F C2..F4.";
+      // *faulty_bytes = 1;
+      return false;
+    }
+  }
+
+  return true;
+}

package/src/is/wasm.spec.ts

@@ -0,0 +1,20 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { isWasm } from './index.js';
+
+describe('isWasm', (): void => {
+  it('is false on no value', (): void => {
+    expect(isWasm()).toEqual(false);
+  });
+
+  it('is false on non-wasm header', (): void => {
+    expect(isWasm(new Uint8Array([1, 2, 3]))).toEqual(false);
+  });
+
+  it('is true when a wasm header is found', (): void => {
+    expect(isWasm(new Uint8Array([0, 97, 115, 109, 1, 2, 3]))).toEqual(true);
+  });
+});

package/src/is/wasm.ts

@@ -0,0 +1,17 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { u8aEq } from '../u8a/eq.js';
+import { isU8a } from './u8a.js';
+
+const WASM_MAGIC = new Uint8Array([0, 97, 115, 109]); // \0asm
+
+/**
+ * @name isWasm
+ * @summary Tests if the input has a WASM header
+ * @description
+ * Checks to see if the input Uint8Array contains a valid WASM header
+ */
+export function isWasm (value?: unknown): value is Uint8Array {
+  return isU8a(value) && u8aEq(value.subarray(0, 4), WASM_MAGIC);
+}