@pezkuwi/util 14.0.22 → 14.0.23

package/src/is/instanceOf.spec.ts

@@ -0,0 +1,48 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { isInstanceOf } from './index.js';
+
+describe('isInstanceOf', (): void => {
+  it('returns true on real instances', (): void => {
+    expect(
+      isInstanceOf(new Array(2), Array)
+    ).toEqual(true);
+  });
+
+  it('returns true on real instances (inherited)', (): void => {
+    class Test extends Array {
+      // default
+    }
+
+    expect(
+      isInstanceOf(new Test(2), Array)
+    ).toEqual(true);
+  });
+
+  it('returns false on non-allocated instances', (): void => {
+    expect(
+      isInstanceOf([], Array)
+    ).toEqual(true);
+  });
+
+  it('returns false on non-instances', (): void => {
+    expect(
+      isInstanceOf('array', Array)
+    ).toEqual(false);
+  });
+
+  it('returns false when class not specified', (): void => {
+    expect(
+      isInstanceOf('array', Array)
+    ).toEqual(false);
+  });
+
+  it('returns false on wrong class type', (): void => {
+    expect(
+      isInstanceOf(new Array(2), String)
+    ).toEqual(false);
+  });
+});

package/src/is/instanceOf.ts

@@ -0,0 +1,24 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @name isInstanceOf
+ * @summary Tests for a instance of a class.
+ * @description
+ * Checks to see if the input value is an instance of the test class.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { isInstanceOf } from '@pezkuwi/util';
+ *
+ * console.log('isInstanceOf', isInstanceOf(new Array(0), Array)); // => true
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/ban-types
+export function isInstanceOf (value: unknown, Clazz: Function): boolean {
+  return (
+    ((value && (value as Record<string, unknown>).constructor) === Clazz) ||
+    value instanceof Clazz
+  );
+}

package/src/is/ip.spec.ts

@@ -0,0 +1,50 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { isIp } from './index.js';
+
+describe('isIp', (): void => {
+  it('returns false when non-ip found', (): void => {
+    expect(
+      isIp('not.an.ip.1')
+    ).toEqual(false);
+  });
+
+  it('returns true on IPv4 addresses', (): void => {
+    expect(
+      isIp('192.168.0.1')
+    ).toEqual(true);
+  });
+
+  it('returns true on IPv4 addresses (IPV4 type)', (): void => {
+    expect(
+      isIp('192.168.0.1', 'v4')
+    ).toEqual(true);
+  });
+
+  it('returns false on IPv4 addresses (IPv6 type)', (): void => {
+    expect(
+      isIp('192.168.0.1', 'v6')
+    ).toEqual(false);
+  });
+
+  it('returns true on IPv6 addresses', (): void => {
+    expect(
+      isIp('1:2:3:4:5:6:7:8')
+    ).toEqual(true);
+  });
+
+  it('returns true on IPv6 addresses (IPv6 type)', (): void => {
+    expect(
+      isIp('1:2:3:4:5:6:7:8', 'v6')
+    ).toEqual(true);
+  });
+
+  it('returns false on IPv6 addresses (IPv4 type)', (): void => {
+    expect(
+      isIp('1:2:3:4:5:6:7:8', 'v4')
+    ).toEqual(false);
+  });
+});

package/src/is/ip.ts

@@ -0,0 +1,56 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+// The regex patterns below were copied as-is from the ip-regex package 5.0.0,
+// https://github.com/sindresorhus/ip-regex/blob/a2a44dfa7f776528158c2a5ff9d8a1be435ec1b9/index.js#L1
+//
+// MIT License
+// Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
+//
+// Changes made:
+//  - boundary support option has been dropped
+//  - only exact matching is used (isIp always passed exact: true)
+//  - the newest ip-regex is ESM-only, we compile to all platforms
+const v4 = '(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]\\d|\\d)(?:\\.(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]\\d|\\d)){3}';
+const v6s = '[a-fA-F\\d]{1,4}';
+const v6 = `
+(?:
+(?:${v6s}:){7}(?:${v6s}|:)|                                    // 1:2:3:4:5:6:7::  1:2:3:4:5:6:7:8
+(?:${v6s}:){6}(?:${v4}|:${v6s}|:)|                             // 1:2:3:4:5:6::    1:2:3:4:5:6::8   1:2:3:4:5:6::8  1:2:3:4:5:6::1.2.3.4
+(?:${v6s}:){5}(?::${v4}|(?::${v6s}){1,2}|:)|                   // 1:2:3:4:5::      1:2:3:4:5::7:8   1:2:3:4:5::8    1:2:3:4:5::7:1.2.3.4
+(?:${v6s}:){4}(?:(?::${v6s}){0,1}:${v4}|(?::${v6s}){1,3}|:)| // 1:2:3:4::        1:2:3:4::6:7:8   1:2:3:4::8      1:2:3:4::6:7:1.2.3.4
+(?:${v6s}:){3}(?:(?::${v6s}){0,2}:${v4}|(?::${v6s}){1,4}|:)| // 1:2:3::          1:2:3::5:6:7:8   1:2:3::8        1:2:3::5:6:7:1.2.3.4
+(?:${v6s}:){2}(?:(?::${v6s}){0,3}:${v4}|(?::${v6s}){1,5}|:)| // 1:2::            1:2::4:5:6:7:8   1:2::8          1:2::4:5:6:7:1.2.3.4
+(?:${v6s}:){1}(?:(?::${v6s}){0,4}:${v4}|(?::${v6s}){1,6}|:)| // 1::              1::3:4:5:6:7:8   1::8            1::3:4:5:6:7:1.2.3.4
+(?::(?:(?::${v6s}){0,5}:${v4}|(?::${v6s}){1,7}|:))             // ::2:3:4:5:6:7:8  ::2:3:4:5:6:7:8  ::8             ::1.2.3.4
+)(?:%[0-9a-zA-Z]{1,})?                                             // %eth0            %1
+`.replace(/\s*\/\/.*$/gm, '').replace(/\n/g, '').trim();
+
+const v46Exact = new RegExp(`(?:^${v4}$)|(?:^${v6}$)`);
+const v4exact = new RegExp(`^${v4}$`);
+const v6exact = new RegExp(`^${v6}$`);
+
+/**
+ * @name isIp
+ * @summary Tests if the value is a valid IP address
+ * @description
+ * Checks to see if the value is a valid IP address. Optionally check for either v4/v6
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { isIp } from '@pezkuwi/util';
+ *
+ * isIp('192.168.0.1')); // => true
+ * isIp('1:2:3:4:5:6:7:8'); // => true
+ * isIp('192.168.0.1', 'v6')); // => false
+ * isIp('1:2:3:4:5:6:7:8', 'v4'); // => false
+ * ```
+ */
+export function isIp (value: string, type?: 'v4' | 'v6'): boolean {
+  switch (type) {
+    case 'v4': return v4exact.test(value);
+    case 'v6': return v6exact.test(value);
+    default: return v46Exact.test(value);
+  }
+}

package/src/is/jsonObject.spec.ts

@@ -0,0 +1,51 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { isJsonObject } from './index.js';
+
+const jsonObject = `{
+    "Test": "1234",
+    "NestedTest": {
+      "Test": "5678"
+    }
+  }`;
+
+describe('isJsonObject', (): void => {
+  it('returns true on empty objects', (): void => {
+    expect(
+      isJsonObject({})
+    ).toEqual(true);
+  });
+
+  it('returns true on JSON objects', (): void => {
+    expect(
+      isJsonObject(jsonObject)
+    ).toEqual(true);
+  });
+
+  it('returns false on JSON parsable value typeof number', (): void => {
+    expect(
+      isJsonObject(1234)
+    ).toEqual(false);
+  });
+
+  it('returns false on JSON parsable value null', (): void => {
+    expect(
+      isJsonObject(null)
+    ).toEqual(false);
+  });
+
+  it('returns false on invalid objects', (): void => {
+    expect(
+      isJsonObject('notAnObject')
+    ).toEqual(false);
+  });
+
+  it('returns false on invalid JSON', (): void => {
+    expect(
+      isJsonObject('{"abc", "def"}')
+    ).toEqual(false);
+  });
+});

package/src/is/jsonObject.ts

@@ -0,0 +1,45 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { stringify } from '../stringify.js';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type ObjectIndexed = Record<string, any>;
+
+/**
+ * @name isJsonObject
+ * @summary Tests for a valid JSON `object`.
+ * @description
+ * Checks to see if the input value is a valid JSON object.
+ * It returns false if the input is JSON parsable, but not an Javascript object.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { isJsonObject } from '@pezkuwi/util';
+ *
+ * isJsonObject({}); // => true
+ * isJsonObject({
+ *  "Test": "1234",
+ *  "NestedTest": {
+ *   "Test": "5678"
+ *  }
+ * }); // => true
+ * isJsonObject(1234); // JSON parsable, but not an object =>  false
+ * isJsonObject(null); // JSON parsable, but not an object => false
+ * isJsonObject('not an object'); // => false
+ * ```
+ */
+export function isJsonObject (value: unknown): value is ObjectIndexed {
+  const str = typeof value !== 'string'
+    ? stringify(value)
+    : value;
+
+  try {
+    const obj = JSON.parse(str) as unknown;
+
+    return typeof obj === 'object' && obj !== null;
+  } catch {
+    return false;
+  }
+}

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

package/src/is/null.ts

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

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

package/src/is/number.ts

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

package/src/is/object.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 { isObject } from './index.js';
+
+describe('isObject', (): void => {
+  it('returns true on valid objects', (): void => {
+    expect(
+      isObject({})
+    ).toEqual(true);
+  });
+
+  it('returns false on invalid objects', (): void => {
+    expect(
+      isObject('notAnObject')
+    ).toEqual(false);
+  });
+
+  it('returns false on null', (): void => {
+    expect(
+      isObject(null)
+    ).toEqual(false);
+  });
+
+  it('returns false on bigint', (): void => {
+    expect(
+      isObject(123n)
+    ).toEqual(false);
+  });
+});

package/src/is/object.ts

@@ -0,0 +1,24 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type ObjectIndexed = Record<string, any>;
+
+/**
+ * @name isObject
+ * @summary Tests for an `object`.
+ * @description
+ * Checks to see if the input value is a JavaScript object.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { isObject } from '@pezkuwi/util';
+ *
+ * isObject({}); // => true
+ * isObject('something'); // => false
+ * ```
+ */
+export function isObject <T extends ObjectIndexed = ObjectIndexed> (value?: unknown): value is T {
+  return !!value && typeof value === 'object';
+}

package/src/is/observable.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 { isObservable } from './index.js';
+
+describe('isObservable', (): void => {
+  it('returns true on valid observables', (): void => {
+    expect(
+      isObservable({ next: (): boolean => true })
+    ).toEqual(true);
+  });
+
+  it('returns false on invalid objects', (): void => {
+    expect(
+      isObservable('notAnObservable')
+    ).toEqual(false);
+  });
+
+  it('returns false on invalid next functions', (): void => {
+    expect(
+      isObservable({ next: true })
+    ).toEqual(false);
+  });
+});

package/src/is/observable.ts

@@ -0,0 +1,22 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Observable } from '../types.js';
+
+import { isOn } from './helpers.js';
+
+/**
+ * @name isBObservable
+ * @summary Tests for a `Observable` object instance.
+ * @description
+ * Checks to see if the input object is an instance of `BN` (bn.js).
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { isObservable } from '@pezkuwi/util';
+ *
+ * console.log('isObservable', isObservable(...));
+ * ```
+ */
+export const isObservable = /*#__PURE__*/ isOn<Observable>('next');

package/src/is/promise.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 { isPromise } from './index.js';
+
+describe('isPromise', (): void => {
+  it('returns true on valid Promise (Promise-like)', (): void => {
+    expect(
+      isPromise(Promise.resolve(1))
+    ).toEqual(true);
+    expect(
+      isPromise({ catch: () => null, then: () => null })
+    ).toEqual(true);
+  });
+
+  it('returns false on invalid objects', (): void => {
+    expect(
+      isPromise('notAnObservable')
+    ).toEqual(false);
+  });
+
+  it('returns false on invalid catch/then functions', (): void => {
+    expect(
+      isPromise({ catch: () => null, then: true })
+    ).toEqual(false);
+    expect(
+      isPromise({ catch: true, then: () => null })
+    ).toEqual(false);
+  });
+});

package/src/is/promise.ts

@@ -0,0 +1,6 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { isOnObject } from './helpers.js';
+
+export const isPromise = /*#__PURE__*/ isOnObject<Promise<unknown>>('catch', 'then');

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());
+}