@pezkuwi/util 14.0.5 → 14.0.6

package/src/extractTime.ts

@@ -0,0 +1,71 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Time } from './types.js';
+
+const MIN_MS = 60 * 1000;
+const HR_MS = MIN_MS * 60;
+const DAY_MS = HR_MS * 24;
+const ZERO: Time = { days: 0, hours: 0, milliseconds: 0, minutes: 0, seconds: 0 };
+
+/** @internal */
+function add (a: Partial<Time>, b: Time): Time {
+  return {
+    days: (a.days || 0) + b.days,
+    hours: (a.hours || 0) + b.hours,
+    milliseconds: (a.milliseconds || 0) + b.milliseconds,
+    minutes: (a.minutes || 0) + b.minutes,
+    seconds: (a.seconds || 0) + b.seconds
+  };
+}
+
+/** @internal */
+function extractSecs (ms: number): Time {
+  const s = ms / 1000;
+
+  if (s < 60) {
+    const seconds = ~~s;
+
+    return add({ seconds }, extractTime(ms - (seconds * 1000)));
+  }
+
+  const m = s / 60;
+
+  if (m < 60) {
+    const minutes = ~~m;
+
+    return add({ minutes }, extractTime(ms - (minutes * MIN_MS)));
+  }
+
+  const h = m / 60;
+
+  if (h < 24) {
+    const hours = ~~h;
+
+    return add({ hours }, extractTime(ms - (hours * HR_MS)));
+  }
+
+  const days = ~~(h / 24);
+
+  return add({ days }, extractTime(ms - (days * DAY_MS)));
+}
+
+/**
+ * @name extractTime
+ * @summary Convert a quantity of seconds to Time array representing accumulated {days, minutes, hours, seconds, milliseconds}
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { extractTime } from '@pezkuwi/util';
+ *
+ * const { days, minutes, hours, seconds, milliseconds } = extractTime(6000); // 0, 0, 10, 0, 0
+ * ```
+ */
+export function extractTime (milliseconds?: number): Time {
+  return !milliseconds
+    ? ZERO
+    : milliseconds < 1000
+      ? add({ milliseconds }, ZERO)
+      : extractSecs(milliseconds);
+}

package/src/float/index.ts

@@ -0,0 +1,4 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+export { floatToU8a } from './toU8a.js';

package/src/float/toU8a.spec.ts

@@ -0,0 +1,52 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { u8aToHex } from '../u8a/index.js';
+import { floatToU8a } from './index.js';
+
+class ExtNumber extends Number {
+  foo = 'bar';
+}
+
+class ExtString extends String {
+  foo = 'bar';
+}
+
+// NOTE Hex value outputs created via online conversion tool:
+// https://www.h-schmidt.net/FloatConverter/IEEE754.html
+// eslint-disable-next-line @typescript-eslint/ban-types
+const TESTS: [isLe: boolean | undefined, bitLength: 32 | 64 | undefined, input: String | string | number | Number, output: string][] = [
+  [undefined, undefined, +0.0, '0x00000000'],
+  [undefined, undefined, -0.0, '0x00000080'],
+  [undefined, undefined, 123.456, '0x79e9f642'],
+  [undefined, undefined, '123.456', '0x79e9f642'],
+  [undefined, undefined, new ExtNumber(123.456), '0x79e9f642'],
+  [undefined, undefined, new ExtString(123.456), '0x79e9f642'],
+  [true, 32, new ExtString(123.456), '0x79e9f642'],
+  [true, undefined, Number.NaN, '0x0000c07f'],
+  [false, undefined, -0.0, '0x80000000'],
+  [undefined, 64, +0.0, '0x0000000000000000'],
+  [true, 64, -0.0, '0x0000000000000080'],
+  [false, 64, -0.0, '0x8000000000000000'],
+  [undefined, 64, Number.NaN, '0x000000000000f87f']
+];
+
+describe('floatToU8a', (): void => {
+  it('throws on invalid bitLength', (): void => {
+    expect(
+      () => floatToU8a(123, { bitLength: 48 as 32 })
+    ).toThrow();
+  });
+
+  describe('conversion tests', (): void => {
+    TESTS.forEach(([isLe, bitLength, input, output], i): void => {
+      it(`#${i}: correctly encodes ${typeof input === 'number' ? input : input.toString()} (typeof=${typeof input})`, (): void => {
+        expect(
+          u8aToHex(floatToU8a(input, { bitLength, isLe }))
+        ).toEqual(output);
+      });
+    });
+  });
+});

package/src/float/toU8a.ts

@@ -0,0 +1,30 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+interface Options {
+  bitLength?: 32 | 64;
+  isLe?: boolean;
+}
+
+/**
+ * @name floatToU8a
+ * @description Converts a float into a U8a representation (While we don't use BE in SCALE
+ * we still allow for either representation, although, as elsewhere, isLe is default)
+ */
+// eslint-disable-next-line @typescript-eslint/ban-types
+export function floatToU8a (value: String | string | number | Number = 0.0, { bitLength = 32, isLe = true }: Options = {}): Uint8Array {
+  if (bitLength !== 32 && bitLength !== 64) {
+    throw new Error('Invalid bitLength provided, expected 32 or 64');
+  }
+
+  const result = new Uint8Array(bitLength / 8);
+  const dv = new DataView(result.buffer, result.byteOffset);
+
+  if (bitLength === 32) {
+    dv.setFloat32(0, Number(value), isLe);
+  } else {
+    dv.setFloat64(0, Number(value), isLe);
+  }
+
+  return result;
+}

package/src/format/formatBalance.spec.ts

@@ -0,0 +1,296 @@
+// 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 { formatBalance } from './index.js';
+
+const FMT_DEFAULTS = {
+  decimals: 0,
+  unit: 'Unit'
+};
+
+describe('formatBalance', (): void => {
+  const TESTVAL = new BN('123456789000');
+
+  // We mess around with the global setDefaults inside some tests,
+  // ensure we restore it to the defaults straight after each run
+  afterEach((): void => {
+    formatBalance.setDefaults(FMT_DEFAULTS);
+  });
+
+  it('returns options for dropdown', (): void => {
+    formatBalance.setDefaults({ decimals: 0, unit: 'TEST' });
+
+    expect(
+      formatBalance.getOptions()
+    ).toEqual([
+      { power: 0, text: 'TEST', value: '-' },
+      { power: 3, text: 'Kilo', value: 'k' },
+      { power: 6, text: 'Mill', value: 'M' },
+      { power: 9, text: 'Bill', value: 'B' },
+      { power: 12, text: 'Tril', value: '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' }
+    ]);
+  });
+
+  it('can set defaults from array values', (): void => {
+    formatBalance.setDefaults({ decimals: [12, 24], unit: ['Multi', 'Unit'] });
+
+    expect(
+      formatBalance(TESTVAL)
+    ).toEqual('123.4567 mMulti');
+  });
+
+  describe('SI formatting', (): void => {
+    it('formats empty to 0', (): void => {
+      expect(formatBalance()).toEqual('0');
+      expect(formatBalance('0')).toEqual('0');
+    });
+
+    // this is after an issue/test from actual values with forceUnit
+    it('formats 1000 (BN) (decimals = 12, withAll, withZero = false)', (): void => {
+      expect(
+        formatBalance(new BN(1000), { decimals: 12, forceUnit: '-', withAll: true, withSi: false, withZero: true })
+      ).toEqual('0.000000001000');
+    });
+
+    it('formats 123,456,789,000 (decimals=15)', (): void => {
+      expect(
+        formatBalance(TESTVAL, { decimals: 15, withSi: true })
+      ).toEqual('123.4567 µUnit');
+    });
+
+    it('formats 123,456 (decimals=0)', (): void => {
+      expect(
+        formatBalance(123456, { decimals: 0, withSi: true })
+      ).toEqual('123.4560 kUnit');
+    });
+
+    it('formats BigInt numbers', (): void => {
+      expect(
+        formatBalance(123456789000n, { decimals: 15, withSi: true })
+      ).toEqual('123.4567 µUnit');
+    });
+
+    it('formats 123,456,789,000 (decimals=15, old style)', (): void => {
+      expect(
+        formatBalance(TESTVAL, { decimals: 15, withSi: true })
+      ).toEqual('123.4567 µUnit');
+    });
+
+    it('formats 123,456,789,000 (decimals=10, withAll=true)', (): void => {
+      expect(
+        formatBalance(TESTVAL, { decimals: 10, forceUnit: '-', withAll: true, withSi: true })
+      ).toEqual('12.3456789000 Unit');
+    });
+
+    it('formats 123,456,789,000 (decimals=10, withAll=true, withZero=false)', (): void => {
+      expect(
+        formatBalance(TESTVAL, { decimals: 10, forceUnit: '-', withAll: true, withSi: true, withZero: false })
+      ).toEqual('12.3456789 Unit');
+    });
+
+    it('formats 123,000,000,000 (decimals=9, withAll=true, withZero=false)', (): void => {
+      expect(
+        formatBalance('123000000000', { decimals: 9, forceUnit: '-', withAll: true, withSi: true, withZero: false })
+      ).toEqual('123 Unit');
+    });
+
+    it('formats 123,456,789,000 (decimals=15, Compact)', (): void => {
+      const compact = {
+        something: 'else',
+        toBn: (): BN => TESTVAL,
+        unwrap: (): BN => TESTVAL
+      };
+
+      expect(
+        formatBalance(compact, { decimals: 15, withSi: true })
+      ).toEqual('123.4567 µUnit');
+    });
+
+    it('formats 123,456,789,000 (decimals=12)', (): void => {
+      expect(
+        formatBalance(TESTVAL, { decimals: 12, withSi: true })
+      ).toEqual('123.4567 mUnit');
+    });
+
+    it('formats 123,456,789,000 (decimals=9)', (): void => {
+      expect(
+        formatBalance(TESTVAL, { decimals: 9, withSi: true })
+      ).toEqual('123.4567 Unit');
+    });
+
+    it('formats 123,456,789,000 (decimals=9, no unit)', (): void => {
+      expect(
+        formatBalance(TESTVAL, { decimals: 9, withSi: true, withUnit: false })
+      ).toEqual('123.4567');
+    });
+
+    it('formats 123,456,789,000 (decimals=9, unit given)', (): void => {
+      expect(
+        formatBalance(TESTVAL, { decimals: 9, withSi: true, withUnit: 'FOO' })
+      ).toEqual('123.4567 FOO');
+    });
+
+    it('formats 123,456,789,000 (decimals=12, no SI)', (): void => {
+      expect(
+        formatBalance(TESTVAL, { decimals: 12, withSi: false })
+      ).toEqual('123.4567');
+    });
+
+    it('formats 123,456,789,000 (decimals=12, full SI)', (): void => {
+      expect(
+        formatBalance(TESTVAL, { decimals: 12, withSiFull: true })
+      ).toEqual('123.4567 milli Unit');
+    });
+
+    it('formats 123,456,789,000 (decimals=12, full SI, no unit)', (): void => {
+      expect(
+        formatBalance(TESTVAL, { decimals: 12, withSiFull: true, withUnit: false })
+      ).toEqual('123.4567 milli');
+    });
+
+    it('formats 123,456,789,000 (decimals=9, full SI)', (): void => {
+      expect(
+        formatBalance(TESTVAL, { decimals: 9, withSiFull: true })
+      ).toEqual('123.4567 Unit');
+    });
+
+    it('formats 123,456,789,000 (decimals=6)', (): void => {
+      expect(
+        formatBalance(TESTVAL, { decimals: 6, withSi: true })
+      ).toEqual('123.4567 kUnit');
+    });
+
+    it('formats 123,456,789,000 (decimals=6, unit specified)', (): void => {
+      expect(
+        formatBalance(TESTVAL, { decimals: 6, withSi: true, withUnit: 'BAR' })
+      ).toEqual('123.4567 kBAR');
+    });
+
+    it('formats 123,456,789,000 (decimals=0, unit specified)', (): void => {
+      expect(
+        formatBalance(TESTVAL, { decimals: 0, withSi: true, withUnit: 'BAR' })
+      ).toEqual('123.4567 BBAR');
+    });
+
+    it('formats 123,456,789,000 * 10 (decimals=12)', (): void => {
+      expect(
+        formatBalance(TESTVAL.muln(10), { decimals: 12, withSi: true })
+      ).toEqual('1.2345 Unit');
+    });
+
+    it('formats 123,456,789,000 * 100 (decimals=12)', (): void => {
+      expect(
+        formatBalance(TESTVAL.muln(100), { decimals: 12, withSi: true })
+      ).toEqual('12.3456 Unit');
+    });
+
+    it('formats 123,456,789,000 * 1000 (decimals=12)', (): void => {
+      expect(
+        formatBalance(TESTVAL.muln(1000), { decimals: 12, withSi: true })
+      ).toEqual('123.4567 Unit');
+    });
+
+    it('formats -123,456,789,000 (decimals=15)', (): void => {
+      expect(
+        formatBalance(new BN('-123456789000'), { decimals: 15, withSi: true })
+      ).toEqual('-123.4567 µUnit');
+    });
+  });
+
+  describe('Forced formatting', (): void => {
+    it('formats 123,456,789,000 (decimals=12, forceUnit=base)', (): void => {
+      expect(
+        formatBalance(TESTVAL, { decimals: 12, forceUnit: '-' })
+      ).toEqual('0.1234 Unit');
+    });
+
+    it('formats 123,456,789,000 (decimals=9, forceUnit=base)', (): void => {
+      expect(
+        formatBalance(TESTVAL, { decimals: 9, forceUnit: '-' })
+      ).toEqual('123.4567 Unit');
+    });
+
+    it('formats 123,456,789,000 (decimals=7, forceUnit=base)', (): void => {
+      expect(
+        formatBalance(TESTVAL, { decimals: 7, forceUnit: '-' })
+      ).toEqual('12,345.6789 Unit');
+    });
+
+    it('formats 123,456,789,000 (decimals=15, forceUnit=micro)', (): void => {
+      expect(
+        formatBalance(TESTVAL, { decimals: 15, forceUnit: 'µ' })
+      ).toEqual('123.4567 µUnit');
+    });
+
+    it('formats 123,456 (decimals=0, locale=sl)', (): void => {
+      expect(
+        formatBalance(123456, { decimals: 0, locale: 'sl', withSi: true })
+      ).toEqual('123,4560 kUnit');
+    });
+
+    it('formats BigInt numbers (locale=sl)', (): void => {
+      expect(
+        formatBalance(123456789000n, { decimals: 15, locale: 'sl', withSi: true })
+      ).toEqual('123,4567 µUnit');
+    });
+
+    it('formats 123,456,789,000 (decimals=7, forceUnit=base locale=sl)', (): void => {
+      expect(
+        formatBalance(TESTVAL, { decimals: 7, forceUnit: '-', locale: 'sl' })
+      ).toEqual('12.345,6789 Unit');
+    });
+  });
+
+  describe('calcSi', (): void => {
+    it('exposes calcSi on formatBalance', (): void => {
+      expect(
+        formatBalance.calcSi('12345').value
+      ).toEqual('k');
+    });
+  });
+
+  describe('findSi', (): void => {
+    it('finds the SI value', (): void => {
+      expect(
+        formatBalance.findSi('k')
+      ).toEqual({ power: 3, text: 'Kilo', value: 'k' });
+    });
+
+    it('returns default on not found', (): void => {
+      expect(
+        formatBalance.findSi('blah')
+      ).toEqual({ power: 0, text: 'Unit', value: '-' });
+    });
+  });
+
+  describe('defaults', (): void => {
+    it('returns defaults', (): void => {
+      expect(
+        formatBalance.getDefaults()
+      ).toEqual(FMT_DEFAULTS);
+    });
+
+    it('formats 123,456,789,000 (defaultDecimals=12)', (): void => {
+      formatBalance.setDefaults({ decimals: 12 });
+
+      expect(
+        formatBalance(TESTVAL)
+      ).toEqual('123.4567 mUnit');
+    });
+
+    it('formats 123,456,789,000 (defaultUnit=TEST)', (): void => {
+      formatBalance.setDefaults({ decimals: 12, unit: 'TEST' });
+
+      expect(
+        formatBalance(TESTVAL)
+      ).toEqual('123.4567 mTEST');
+    });
+  });
+});

package/src/format/formatBalance.ts

@@ -0,0 +1,177 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { BN } from '../bn/bn.js';
+import type { SiDef, ToBn } from '../types.js';
+
+import { bnToBn } from '../bn/toBn.js';
+import { isBoolean } from '../is/boolean.js';
+import { formatDecimal } from './formatDecimal.js';
+import { getSeparator } from './getSeparator.js';
+import { calcSi, findSi, SI, SI_MID } from './si.js';
+
+interface Defaults {
+  decimals: number;
+  unit: string;
+}
+
+interface SetDefaults {
+  decimals?: number[] | number;
+  unit?: string[] | string;
+}
+
+interface Options {
+  /**
+   * @description The number of decimals
+   */
+  decimals?: number;
+  /**
+   * @description Format the number with this specific unit
+   */
+  forceUnit?: string;
+  /**
+   * @description Returns value using all available decimals
+   */
+  withAll?: boolean;
+  /**
+   * @description Format with SI, i.e. m/M/etc. (default = true)
+   */
+  withSi?: boolean;
+  /**
+   * @description Format with full SI, i.e. mili/Mega/etc.
+   */
+  withSiFull?: boolean;
+  /**
+   * @description Add the unit (useful in Balance formats)
+   */
+  withUnit?: boolean | string;
+  /**
+   * @description Returns all trailing zeros, otherwise removes (default = true)
+   */
+  withZero?: boolean;
+  /**
+   * @description The locale to use
+   */
+  locale?: string;
+}
+
+interface BalanceFormatter {
+  <ExtToBn extends ToBn> (input?: number | string | BN | bigint | ExtToBn, options?: Options): string;
+  calcSi (text: string, decimals?: number): SiDef;
+  findSi (type: string): SiDef;
+  getDefaults (): Defaults;
+  getOptions (decimals?: number): SiDef[];
+  setDefaults (defaults: SetDefaults): void;
+}
+
+const DEFAULT_DECIMALS = 0;
+const DEFAULT_UNIT = SI[SI_MID].text;
+
+let defaultDecimals = DEFAULT_DECIMALS;
+let defaultUnit = DEFAULT_UNIT;
+
+// Formats a string/number with <prefix>.<postfix><type> notation
+function _formatBalance <ExtToBn extends ToBn> (input?: number | string | BN | bigint | ExtToBn, { decimals = defaultDecimals, forceUnit, locale = 'en', withAll = false, withSi = true, withSiFull = false, withUnit = true, withZero = true }: Options = {}): string {
+  // we only work with string inputs here - convert anything
+  // into the string-only value
+  let text = bnToBn(input).toString();
+
+  if (text.length === 0 || text === '0') {
+    return '0';
+  }
+
+  // strip the negative sign so we can work with clean groupings, re-add this in the
+  // end when we return the result (from here on we work with positive numbers)
+  let sign = '';
+
+  if (text[0].startsWith('-')) {
+    sign = '-';
+    text = text.substring(1);
+  }
+
+  // We start at midpoint (8) minus 1 - this means that values display as
+  // 123.4567 instead of 0.1234 k (so we always have the most relevant).
+  const si = calcSi(text, decimals, forceUnit);
+  const mid = text.length - (decimals + si.power);
+  const pre = mid <= 0 ? '0' : text.substring(0, mid);
+
+  // get the post from the midpoint onward and then first add max decimals
+  // before trimming to the correct (calculated) amount of decimals again
+  let post = text
+    .padStart(mid < 0 ? decimals : 1, '0')
+    .substring(mid < 0 ? 0 : mid)
+    .padEnd(withAll ? Math.max(decimals, 4) : 4, '0')
+    .substring(0, withAll ? Math.max(4, decimals + si.power) : 4);
+
+  // remove all trailing 0's (if required via flag)
+  if (!withZero) {
+    let end = post.length - 1;
+
+    // This looks inefficient, however it is better to do the checks and
+    // only make one final slice than it is to do it in multiples
+    do {
+      if (post[end] === '0') {
+        end--;
+      }
+    } while (post[end] === '0');
+
+    post = post.substring(0, end + 1);
+  }
+
+  // the display unit
+  const unit = isBoolean(withUnit)
+    ? SI[SI_MID].text
+    : withUnit;
+
+  // format the units for display based on the flags
+  const units = withSi || withSiFull
+    ? si.value === '-'
+      ? withUnit
+        ? ` ${unit}`
+        : ''
+      : ` ${withSiFull ? `${si.text}${withUnit ? ' ' : ''}` : si.value}${withUnit ? unit : ''}`
+    : '';
+
+  const { decimal, thousand } = getSeparator(locale);
+
+  return `${sign}${formatDecimal(pre, thousand)}${post && `${decimal}${post}`}${units}`;
+}
+
+export const formatBalance = _formatBalance as BalanceFormatter;
+
+formatBalance.calcSi = (text: string, decimals: number = defaultDecimals): SiDef =>
+  calcSi(text, decimals);
+
+formatBalance.findSi = findSi;
+
+formatBalance.getDefaults = (): Defaults => {
+  return {
+    decimals: defaultDecimals,
+    unit: defaultUnit
+  };
+};
+
+// get allowable options to display in a dropdown
+formatBalance.getOptions = (decimals: number = defaultDecimals): SiDef[] => {
+  return SI.filter(({ power }): boolean =>
+    power < 0
+      ? (decimals + power) >= 0
+      : true
+  );
+};
+
+// Sets the default decimals to use for formatting (ui-wide)
+formatBalance.setDefaults = ({ decimals, unit }: SetDefaults): void => {
+  defaultDecimals = (
+    Array.isArray(decimals)
+      ? decimals[0]
+      : decimals
+  ) ?? defaultDecimals;
+  defaultUnit = (
+    Array.isArray(unit)
+      ? unit[0]
+      : unit
+  ) ?? defaultUnit;
+
+  SI[SI_MID].text = defaultUnit;
+};

package/src/format/formatDate.spec.ts

@@ -0,0 +1,17 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { formatDate } from './index.js';
+
+describe('formatDate', (): void => {
+  it('formats a known date into the correct format', (): void => {
+    const date = new Date(Date.UTC(2020, 1, 15, 11, 14, 34));
+
+    // make this test-locale agnostic
+    date.setTime(date.getTime() + date.getTimezoneOffset() * 60 * 1000);
+
+    expect(formatDate(date)).toEqual('2020-02-15 11:14:34');
+  });
+});

package/src/format/formatDate.ts

@@ -0,0 +1,22 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/** @internal */
+function zeroPad (value: number): string {
+  return value.toString().padStart(2, '0');
+}
+
+/**
+ * @name formatDate
+ * @description Formats a date in CCYY-MM-DD HH:MM:SS format
+ */
+export function formatDate (date: Date): string {
+  const year = date.getFullYear().toString();
+  const month = zeroPad((date.getMonth() + 1));
+  const day = zeroPad(date.getDate());
+  const hour = zeroPad(date.getHours());
+  const minute = zeroPad(date.getMinutes());
+  const second = zeroPad(date.getSeconds());
+
+  return `${year}-${month}-${day} ${hour}:${minute}:${second}`;
+}