@pezkuwi/util 14.0.21 → 14.0.23

package/src/format/formatElapsed.ts

@@ -0,0 +1,35 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { BN } from '../bn/bn.js';
+import type { ToBn } from '../types.js';
+
+import { bnToBn } from '../bn/toBn.js';
+
+/** @internal */
+function formatValue (elapsed: number): string {
+  if (elapsed < 15) {
+    return `${elapsed.toFixed(1)}s`;
+  } else if (elapsed < 60) {
+    return `${elapsed | 0}s`;
+  } else if (elapsed < 3600) {
+    return `${elapsed / 60 | 0}m`;
+  }
+
+  return `${elapsed / 3600 | 0}h`;
+}
+
+/**
+ * @name formatElapsed
+ * @description Formats an elapsed value into s, m, h or day segments
+ */
+export function formatElapsed <ExtToBn extends ToBn> (now?: Date | null, value?: bigint | BN | ExtToBn | Date | number | null): string {
+  const tsNow = now?.getTime() || 0;
+  const tsValue = value instanceof Date
+    ? value.getTime()
+    : bnToBn(value).toNumber();
+
+  return (tsNow && tsValue)
+    ? formatValue(Math.max(Math.abs(tsNow - tsValue), 0) / 1000)
+    : '0.0s';
+}

package/src/format/formatNumber.spec.ts

@@ -0,0 +1,60 @@
+// 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 { formatNumber } from './index.js';
+
+describe('formatNumber', (): void => {
+  it('formats empty', (): void => {
+    expect(
+      formatNumber()
+    ).toEqual('0');
+  });
+
+  it('formats negative numbers', (): void => {
+    expect(
+      formatNumber(-123456)
+    ).toEqual('-123,456');
+  });
+
+  it('formats BN numbers', (): void => {
+    expect(
+      formatNumber(new BN(12345))
+    ).toEqual('12,345');
+  });
+
+  it('formats BigInt numbers', (): void => {
+    expect(
+      formatNumber(123456789n)
+    ).toEqual('123,456,789');
+  });
+
+  it('formats Compact<BN>', (): void => {
+    expect(
+      formatNumber({
+        toBn: (): BN => new BN(12345),
+        unwrap: (): BN => new BN(0)
+      })
+    ).toEqual('12,345');
+  });
+
+  it('formats negative numbers (locale=sl)', (): void => {
+    expect(
+      formatNumber(-123456, { locale: 'sl' })
+    ).toEqual('-123.456');
+  });
+
+  it('formats BN numbers (locale=sl)', (): void => {
+    expect(
+      formatNumber(new BN(12345), { locale: 'sl' })
+    ).toEqual('12.345');
+  });
+
+  it('formats BigInt numbers (locale=sl)', (): void => {
+    expect(
+      formatNumber(123456789n, { locale: 'sl' })
+    ).toEqual('123.456.789');
+  });
+});

package/src/format/formatNumber.ts

@@ -0,0 +1,29 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { BN } from '../bn/bn.js';
+import type { ToBn } from '../types.js';
+
+import { bnToBn } from '../bn/toBn.js';
+import { formatDecimal } from './formatDecimal.js';
+import { getSeparator } from './getSeparator.js';
+
+interface Options {
+  /**
+   * @description The locale to use
+   */
+  locale?: string;
+}
+
+/**
+ * @name formatNumber
+ * @description Formats a number into string format with thousand separators
+ */
+export function formatNumber <ExtToBn extends ToBn> (
+  value?: ExtToBn | BN | bigint | number | null,
+  { locale = 'en' }: Options = {}
+): string {
+  const { thousand } = getSeparator(locale);
+
+  return formatDecimal(bnToBn(value).toString(), thousand);
+}

package/src/format/getSeparator.spec.ts

@@ -0,0 +1,53 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { getSeparator } from './getSeparator.js';
+
+describe('getSeparator', (): void => {
+  const normalizeSeparator = (separator: string) =>
+    separator === '\u202F' ? ' ' : separator;
+
+  const testLocales = [
+    { decimal: '.', locale: 'en', thousand: ',' },
+    { decimal: '.', locale: 'en-gb', thousand: ',' },
+    { decimal: ',', locale: 'sl', thousand: '.' },
+    { decimal: ',', locale: 'sl-si', thousand: '.' },
+    { decimal: ',', locale: 'it-it', thousand: '.' },
+    { decimal: '.', locale: 'ja-jp', thousand: ',' },
+    { decimal: '.', locale: 'hi-IN', thousand: ',' },
+    { decimal: '.', locale: undefined, thousand: ',' } // Fallback test
+  ];
+
+  testLocales.forEach(({ decimal, locale, thousand }) => {
+    it(`uses ${locale || 'system default'} locale`, (): void => {
+      expect(
+        getSeparator(locale)
+      ).toEqual({ decimal, thousand });
+    });
+  });
+
+  it('falls back for invalid locale', (): void => {
+    expect(
+      getSeparator('invalid-locale')
+    ).toEqual({ decimal: '.', thousand: ',' }); // Default fallback
+  });
+
+  it('matches system locale dynamically', (): void => {
+    const n = 1000.1;
+    const expected = {
+      decimal: n.toLocaleString().substring(5, 6),
+      thousand: n.toLocaleString().substring(1, 2)
+    };
+
+    expect(getSeparator()).toEqual(expected);
+  });
+
+  it('handles locales with unique separators', (): void => {
+    const result = getSeparator('fr-FR');
+
+    expect(normalizeSeparator(result.thousand)).toBe(' ');
+    expect(result.decimal).toBe(',');
+  });
+});

package/src/format/getSeparator.ts

@@ -0,0 +1,15 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Get the decimal and thousand separator of a locale
+ * @param locale
+ * @returns {decimal: string, thousand: string}
+ */
+export function getSeparator (locale?: string):
+{ thousand: string, decimal: string } {
+  return {
+    decimal: (0.1).toLocaleString(locale, { useGrouping: false }).charAt(1),
+    thousand: (1000).toLocaleString(locale, { useGrouping: true }).replace(/\d/g, '').charAt(0)
+  };
+}

package/src/format/index.ts

@@ -0,0 +1,9 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+export { formatBalance } from './formatBalance.js';
+export { formatDate } from './formatDate.js';
+export { formatDecimal } from './formatDecimal.js';
+export { formatElapsed } from './formatElapsed.js';
+export { formatNumber } from './formatNumber.js';
+export { calcSi, findSi } from './si.js';

package/src/format/si.ts

@@ -0,0 +1,52 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { SiDef } from '../types.js';
+
+/** @internal */
+export const SI_MID = 8;
+
+/** @internal */
+export const SI: SiDef[] = [
+  { power: -24, text: 'yocto', value: 'y' },
+  { power: -21, text: 'zepto', value: 'z' },
+  { power: -18, text: 'atto', value: 'a' },
+  { power: -15, text: 'femto', value: 'f' },
+  { power: -12, text: 'pico', value: 'p' },
+  { power: -9, text: 'nano', value: 'n' },
+  { power: -6, text: 'micro', value: 'µ' },
+  { power: -3, text: 'milli', value: 'm' },
+  { power: 0, text: 'Unit', value: '-' }, // position 8
+  { power: 3, text: 'Kilo', value: 'k' },
+  { power: 6, text: 'Mill', value: 'M' }, // Mega, M
+  { power: 9, text: 'Bill', value: 'B' }, // Giga, G
+  { power: 12, text: 'Tril', value: 'T' }, // Tera, T
+  { power: 15, text: 'Peta', value: 'P' },
+  { power: 18, text: 'Exa', value: 'E' },
+  { power: 21, text: 'Zeta', value: 'Z' },
+  { power: 24, text: 'Yotta', value: 'Y' }
+];
+
+// Given a SI type (e.g. k, m, Y) find the SI definition
+/** @internal */
+export function findSi (type: string): SiDef {
+  // use a loop here, better RN support (which doesn't have [].find)
+  for (let i = 0, count = SI.length; i < count; i++) {
+    if (SI[i].value === type) {
+      return SI[i];
+    }
+  }
+
+  return SI[SI_MID];
+}
+
+/** @internal */
+export function calcSi (text: string, decimals: number, forceUnit?: string): SiDef {
+  if (forceUnit) {
+    return findSi(forceUnit);
+  }
+
+  const siDefIndex = (SI_MID - 1) + Math.ceil((text.length - decimals) / 3);
+
+  return SI[siDefIndex] || SI[siDefIndex < 0 ? 0 : SI.length - 1];
+}

package/src/has.spec.ts

@@ -0,0 +1,12 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { hasBuffer } from './has.js';
+
+describe('hasBuffer', (): void => {
+  it('has Buffer (Jest + Node.js)', (): void => {
+    expect(hasBuffer).toEqual(typeof Buffer !== 'undefined');
+  });
+});

package/src/has.ts

@@ -0,0 +1,38 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { BufferClass } from './types.js';
+
+import { BigInt } from '@pezkuwi/x-bigint';
+import { xglobal } from '@pezkuwi/x-global';
+
+// Since we run in very different environments, we have to ensure we have all
+// the types used here for detection (some of these may require Node definitions,
+// which are not available in Deno/browser)
+declare const __dirname: unknown;
+declare const module: unknown;
+declare const require: unknown;
+
+/** true if the environment has proper BigInt support */
+export const hasBigInt = typeof BigInt === 'function' && typeof BigInt.asIntN === 'function';
+
+/** true if the environment is CJS */
+export const hasCjs = typeof require === 'function' && typeof module !== 'undefined';
+
+/** true if the environment has __dirname available */
+export const hasDirname = typeof __dirname !== 'undefined';
+
+/** true if the environment is ESM */
+export const hasEsm = !hasCjs;
+
+/** true if the environment has WebAssembly available */
+export const hasWasm = typeof WebAssembly !== 'undefined';
+
+// NOTE We check the following on globalThis, avoiding specific polyfill detection
+// that some bundlers such as parcel would add (this is a check, not a use)
+
+/** true if the environment has support for Buffer (typically Node.js) */
+export const hasBuffer = typeof xglobal.Buffer === 'function' && typeof (xglobal.Buffer as unknown as BufferClass).isBuffer === 'function';
+
+/** true if the environment has process available (typically Node.js) */
+export const hasProcess = typeof xglobal.process === 'object';

package/src/hex/addPrefix.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 { hexAddPrefix } from './index.js';
+
+describe('hexAddPrefix', (): void => {
+  it('does not add when prefix is available', (): void => {
+    expect(
+      hexAddPrefix('0x0123')
+    ).toEqual('0x0123');
+  });
+
+  it('adds the prefix when it is not available', (): void => {
+    expect(
+      hexAddPrefix('0123')
+    ).toEqual('0x0123');
+  });
+
+  it('adds extra 0 when length % 2 === 1', (): void => {
+    expect(
+      hexAddPrefix('123')
+    ).toEqual('0x0123');
+  });
+
+  it('returns null as 0x', (): void => {
+    expect(
+      hexAddPrefix(null)
+    ).toEqual('0x');
+  });
+});

package/src/hex/addPrefix.ts

@@ -0,0 +1,26 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { HexString } from '../types.js';
+
+import { hexHasPrefix } from './hasPrefix.js';
+
+/**
+ * @name hexAddPrefix
+ * @summary Adds the `0x` prefix to string values.
+ * @description
+ * Returns a `0x` prefixed string from the input value. If the input is already prefixed, it is returned unchanged.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { hexAddPrefix } from '@pezkuwi/util';
+ *
+ * console.log('With prefix', hexAddPrefix('0a0b12')); // => 0x0a0b12
+ * ```
+ */
+export function hexAddPrefix (value?: string | null): HexString {
+  return value && hexHasPrefix(value)
+    ? value
+    : `0x${value && value.length % 2 === 1 ? '0' : ''}${value || ''}`;
+}

package/src/hex/fixLength.spec.ts

@@ -0,0 +1,38 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { hexFixLength } from './index.js';
+
+describe('hexFixLength', (): void => {
+  it('returns bitLength === -1 as-is', (): void => {
+    expect(
+      hexFixLength('0x12345678')
+    ).toEqual('0x12345678');
+  });
+
+  it('does not change when bitlength === length', (): void => {
+    expect(
+      hexFixLength('0x12345678', 32)
+    ).toEqual('0x12345678');
+  });
+
+  it('trims values when bitLength > length', (): void => {
+    expect(
+      hexFixLength('0x12345678', 16)
+    ).toEqual('0x5678');
+  });
+
+  it('returns as-is when bitLength < length', (): void => {
+    expect(
+      hexFixLength('0x1234', 32)
+    ).toEqual('0x1234');
+  });
+
+  it('adds zeros when bitLength < length (withPadded)', (): void => {
+    expect(
+      hexFixLength('0x1234', 32, true)
+    ).toEqual('0x00001234');
+  });
+});

package/src/hex/fixLength.ts

@@ -0,0 +1,36 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { HexString } from '../types.js';
+
+import { hexAddPrefix } from './addPrefix.js';
+import { hexStripPrefix } from './stripPrefix.js';
+
+/**
+ * @name hexFixLength
+ * @summary Shifts a hex string to a specific bitLength
+ * @description
+ * Returns a `0x` prefixed string with the specified number of bits contained in the return value. (If bitLength is -1, length checking is not done). Values with more bits are trimmed to the specified length. Input values with less bits are returned as-is by default. When `withPadding` is set, shorter values are padded with `0`.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { hexFixLength } from '@pezkuwi/util';
+ *
+ * console.log('fixed', hexFixLength('0x12', 16)); // => 0x12
+ * console.log('fixed', hexFixLength('0x12', 16, true)); // => 0x0012
+ * console.log('fixed', hexFixLength('0x0012', 8)); // => 0x12
+ * ```
+ */
+export function hexFixLength (value: string, bitLength = -1, withPadding = false): HexString {
+  const strLength = Math.ceil(bitLength / 4);
+  const hexLength = strLength + 2;
+
+  return hexAddPrefix(
+    (bitLength === -1 || value.length === hexLength || (!withPadding && value.length < hexLength))
+      ? hexStripPrefix(value)
+      : (value.length > hexLength)
+        ? hexStripPrefix(value).slice(-1 * strLength)
+        : `${'0'.repeat(strLength)}${hexStripPrefix(value)}`.slice(-1 * strLength)
+  );
+}

package/src/hex/hasPrefix.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 { hexHasPrefix } from './index.js';
+
+describe('hexHasPrefix', (): void => {
+  it('returns true when hex prefix is found', (): void => {
+    expect(
+      hexHasPrefix('0x1234')
+    ).toEqual(true);
+  });
+
+  it('returns false when no prefix attached', (): void => {
+    expect(
+      hexHasPrefix('123')
+    ).toEqual(false);
+  });
+
+  it('returns false when null value supplied', (): void => {
+    expect(
+      hexHasPrefix(null)
+    ).toEqual(false);
+  });
+
+  it('returns false when non-string value supplied', (): void => {
+    expect(
+      hexHasPrefix(false as unknown as string)
+    ).toEqual(false);
+  });
+});

package/src/hex/hasPrefix.ts

@@ -0,0 +1,24 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { HexString } from '../types.js';
+
+import { isHex } from '../is/hex.js';
+
+/**
+ * @name hexHasPrefix
+ * @summary Tests for the existence of a `0x` prefix.
+ * @description
+ * Checks for a valid hex input value and if the start matched `0x`
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { hexHasPrefix } from '@pezkuwi/util';
+ *
+ * console.log('has prefix', hexHasPrefix('0x1234')); // => true
+ * ```
+ */
+export function hexHasPrefix (value?: string | null): value is HexString {
+  return !!value && isHex(value, -1);
+}

package/src/hex/index.ts

@@ -0,0 +1,16 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @summary Internal utilities to create and test for hex values
+ */
+
+export { hexAddPrefix } from './addPrefix.js';
+export { hexFixLength } from './fixLength.js';
+export { hexHasPrefix } from './hasPrefix.js';
+export { hexStripPrefix } from './stripPrefix.js';
+export { hexToBigInt } from './toBigInt.js';
+export { hexToBn } from './toBn.js';
+export { hexToNumber } from './toNumber.js';
+export { hexToString } from './toString.js';
+export { hexToU8a } from './toU8a.js';

package/src/hex/stripPrefix.spec.ts

@@ -0,0 +1,44 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { hexStripPrefix } from './index.js';
+
+describe('hexStripPrefix', (): void => {
+  it('returns an empty string when null value supplied', (): void => {
+    expect(
+      hexStripPrefix(null)
+    ).toEqual('');
+  });
+
+  it('returns an empty string when 0x value supplied', (): void => {
+    expect(
+      hexStripPrefix('0x')
+    ).toEqual('');
+  });
+
+  it('strips the prefix from hex strings', (): void => {
+    expect(
+      hexStripPrefix('0x1223')
+    ).toEqual('1223');
+  });
+
+  it('strips the prefix from hex strings (non 2 lnegth)', (): void => {
+    expect(
+      hexStripPrefix('0x123')
+    ).toEqual('123');
+  });
+
+  it('returns un-prefixed hex as-is', (): void => {
+    expect(
+      hexStripPrefix('abcd1223')
+    ).toEqual('abcd1223');
+  });
+
+  it('throws when invalid hex', (): void => {
+    expect(
+      () => hexStripPrefix('0x0x01ab')
+    ).toThrow(/Expected hex value to convert/);
+  });
+});

package/src/hex/stripPrefix.ts

@@ -0,0 +1,30 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { REGEX_HEX_NOPREFIX, REGEX_HEX_PREFIXED } from '../is/hex.js';
+
+/**
+ * @name hexStripPrefix
+ * @summary Strips any leading `0x` prefix.
+ * @description
+ * Tests for the existence of a `0x` prefix, and returns the value without the prefix. Un-prefixed values are returned as-is.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { hexStripPrefix } from '@pezkuwi/util';
+ *
+ * console.log('stripped', hexStripPrefix('0x1234')); // => 1234
+ * ```
+ */
+export function hexStripPrefix (value?: string | null): string {
+  if (!value || value === '0x') {
+    return '';
+  } else if (REGEX_HEX_PREFIXED.test(value)) {
+    return value.substring(2);
+  } else if (REGEX_HEX_NOPREFIX.test(value)) {
+    return value;
+  }
+
+  throw new Error(`Expected hex value to convert, found '${value}'`);
+}

package/src/hex/toBigInt.spec.ts

@@ -0,0 +1,74 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { hexToBigInt } from './index.js';
+
+describe('hexToBigInt', (): void => {
+  it('converts prefixed hex values to BN', (): void => {
+    expect(
+      hexToBigInt('0x81')
+    ).toEqual(0x81n);
+  });
+
+  it('converts null values to BN(0)', (): void => {
+    expect(
+      hexToBigInt(null)
+    ).toEqual(0n);
+  });
+
+  it('converts 0x values to BN(0)', (): void => {
+    expect(
+      hexToBigInt('0x')
+    ).toEqual(0n);
+  });
+
+  it('should convert with Big Endian by default', (): void => {
+    expect(
+      hexToBigInt('0x0100123456')
+    ).toEqual(0x0100123456n);
+  });
+
+  it('converts 0x values to BN(0) (LE)', (): void => {
+    expect(
+      hexToBigInt('0x', { isLe: true })
+    ).toEqual(0n);
+  });
+
+  it('converts little-endian', (): void => {
+    expect(
+      hexToBigInt('0x4500000000000000', { isLe: true })
+    ).toEqual(69n);
+  });
+
+  it('handles negative numbers (LE)', (): void => {
+    expect(
+      hexToBigInt('0x2efb', { isLe: true, isNegative: true })
+    ).toEqual(-1234n);
+  });
+
+  it('handles negative numbers (BE)', (): void => {
+    expect(
+      hexToBigInt('0xfb2e', { isLe: false, isNegative: true })
+    ).toEqual(-1234n);
+  });
+
+  it('handles negative numbers (LE, 128)', (): void => {
+    expect(
+      hexToBigInt('0x00009c584c491ff2ffffffffffffffff', { isLe: true, isNegative: true })
+    ).toEqual(-1000000000000000000n);
+  });
+
+  it('handles starting zeros correctly (BE)', (): void => {
+    expect(
+      hexToBigInt('0x0000000000000100', { isLe: false })
+    ).toEqual(256n);
+  });
+
+  it('handles starting zeros correctly (LE)', (): void => {
+    expect(
+      hexToBigInt('0x0001000000000000', { isLe: true })
+    ).toEqual(256n);
+  });
+});