@pezkuwi/util 14.0.4 → 14.0.6

package/src/compact/fromU8a.spec.ts

@@ -0,0 +1,84 @@
+// 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/bn.js';
+import { hexToU8a } from '../hex/toU8a.js';
+import { perf } from '../test/index.js';
+import { compactFromU8a, compactFromU8aLim } from './index.js';
+
+describe('compactFromU8a', (): void => {
+  it('decoded u8 value', (): void => {
+    expect(
+      compactFromU8a(new Uint8Array([0b11111100]))
+    ).toEqual([1, new BN(63)]);
+  });
+
+  it('decodes from same u16 encoded value', (): void => {
+    expect(
+      compactFromU8a(new Uint8Array([0b11111101, 0b00000111])).toString()
+    ).toEqual(
+      [2, new BN(511)].toString()
+    );
+  });
+
+  it('decodes from same u32 encoded value (short)', (): void => {
+    expect(
+      compactFromU8a(new Uint8Array([254, 255, 3, 0])).toString()
+    ).toEqual(
+      [4, new BN(0xffff)].toString()
+    );
+  });
+
+  it('decodes from same u32 encoded value (short, max)', (): void => {
+    expect(
+      compactFromU8a(new Uint8Array([254, 255, 255, 255])).toString()
+    ).toEqual(
+      [4, new BN(1073741823)].toString()
+    );
+  });
+
+  it('decodes from same u32 encoded value (full)', (): void => {
+    expect(
+      compactFromU8a(new Uint8Array([3, 249, 255, 255, 255]))
+    ).toEqual([5, new BN(0xfffffff9)]);
+  });
+
+  it('decodes from same u32 as u64 encoded value (full, default)', (): void => {
+    expect(
+      compactFromU8a(new Uint8Array([3 + ((4 - 4) << 2), 249, 255, 255, 255]))
+    ).toEqual([5, new BN(0xfffffff9)]);
+  });
+
+  it('decodes an actual value', (): void => {
+    expect(
+      compactFromU8a(
+        hexToU8a('0x0b00407a10f35a')
+      )
+    ).toEqual([7, new BN('5af3107a4000', 16)]);
+  });
+
+  it('decodes an actual value (Buffer)', (): void => {
+    expect(
+      compactFromU8a(
+        Buffer.from('0b00407a10f35a', 'hex')
+      )
+    ).toEqual([7, new BN('5af3107a4000', 16)]);
+  });
+
+  it('decodes an actual value (100000000)', (): void => {
+    expect(
+      compactFromU8a(
+        hexToU8a('0x0284d717')
+      )[1].toString()
+    ).toEqual('100000000');
+  });
+
+  perf('compactFromU8a (u8)', 1_000_000, [[new Uint8Array([63 << 2])]], compactFromU8a);
+  perf('compactFromU8a (u16)', 1_000_000, [[new Uint8Array([0b11111101, 0b00000111])]], compactFromU8a);
+  perf('compactFromU8a (u32)', 1_000_000, [[new Uint8Array([254, 255, 3, 0])]], compactFromU8a);
+  perf('compactFromU8aLim (u32)', 1_000_000, [[new Uint8Array([254, 255, 3, 0])]], compactFromU8aLim);
+  perf('compactFromU8a (u48)', 1_000_000, [[hexToU8a('0x0b00407a10f35a')]], compactFromU8a);
+  perf('compactFromU8a (u96)', 250_000, [[new Uint8Array([23, 52, 0x40, 0x7a, 0x10, 0xf3, 0x5a, 0, 0, 18])]], compactFromU8a);
+});

package/src/compact/fromU8a.ts

@@ -0,0 +1,109 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { U8aLike } from '../types.js';
+
+import { BN } from '../bn/index.js';
+import { u8aToBn, u8aToU8a } from '../u8a/index.js';
+
+/**
+ * @name compactFromU8a
+ * @description Retrives the offset and encoded length from a compact-prefixed value
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { compactFromU8a } from '@pezkuwi/util';
+ *
+ * const [offset, length] = compactFromU8a(new Uint8Array([254, 255, 3, 0]));
+ *
+ * console.log('value offset=', offset, 'length=', length); // 4, 0xffff
+ * ```
+ */
+export function compactFromU8a (input: U8aLike): [number, BN] {
+  const u8a = u8aToU8a(input);
+
+  // The u8a is manually converted here for 1, 2 & 4 lengths, it is 2x faster
+  // than doing an additional call to u8aToBn (as with variable length)
+  switch (u8a[0] & 0b11) {
+    case 0b00:
+      return [1, new BN(u8a[0] >>> 2)];
+
+    case 0b01:
+      return [2, new BN((u8a[0] + (u8a[1] << 8)) >>> 2)];
+
+    case 0b10:
+      // for the 3rd byte, we don't << 24 - since JS converts all bitwise operators to
+      // 32-bit, in the case where the top-most bit is set this yields a negative value
+      return [4, new BN((u8a[0] + (u8a[1] << 8) + (u8a[2] << 16) + (u8a[3] * 0x1_00_00_00)) >>> 2)];
+
+    // 0b11
+    default: {
+      // add 5 to shifted (4 for base length, 1 for this byte)
+      const offset = (u8a[0] >>> 2) + 5;
+
+      // we unroll the loop
+      switch (offset) {
+        // there still could be 4 bytes data, similar to 0b10 above (with offsets)
+        case 5:
+          // for the 3rd byte, we don't << 24 - since JS converts all bitwise operators to
+          // 32-bit, in the case where the top-most bit is set this yields a negative value
+          return [5, new BN(u8a[1] + (u8a[2] << 8) + (u8a[3] << 16) + (u8a[4] * 0x1_00_00_00))];
+
+        case 6:
+          return [6, new BN(u8a[1] + (u8a[2] << 8) + (u8a[3] << 16) + ((u8a[4] + (u8a[5] << 8)) * 0x1_00_00_00))];
+
+        // 6 bytes data is the maximum, 48 bits (56 would overflow)
+        case 7:
+          return [7, new BN(u8a[1] + (u8a[2] << 8) + (u8a[3] << 16) + ((u8a[4] + (u8a[5] << 8) + (u8a[6] << 16)) * 0x1_00_00_00))];
+
+        // for anything else, use the non-unrolled version
+        default:
+          return [offset, u8aToBn(u8a.subarray(1, offset))];
+      }
+    }
+  }
+}
+
+/**
+ * @name compactFromU8aLim
+ * @description A limited version of [[compactFromU8a]], accepting only Uint8Array inputs for values <= 48 bits
+ */
+export function compactFromU8aLim (u8a: Uint8Array): [number, number] {
+  // The u8a is manually converted here for 1, 2 & 4 lengths, it is 2x faster
+  // than doing an additional call to u8aToBn (as with variable length)
+  switch (u8a[0] & 0b11) {
+    case 0b00:
+      return [1, u8a[0] >>> 2];
+
+    case 0b01:
+      return [2, (u8a[0] + (u8a[1] << 8)) >>> 2];
+
+    case 0b10:
+      // for the 3rd byte, we don't << 24 - since JS converts all bitwise operators to
+      // 32-bit, in the case where the top-most bit is set this yields a negative value
+      return [4, (u8a[0] + (u8a[1] << 8) + (u8a[2] << 16) + (u8a[3] * 0x1_00_00_00)) >>> 2];
+
+    // 0b11
+    default: {
+      // add 5 to shifted (4 for base length, 1 for this byte)
+      // we unroll the loop
+      switch ((u8a[0] >>> 2) + 5) {
+        // there still could be 4 bytes data, similar to 0b10 above (with offsets)
+        case 5:
+          return [5, u8a[1] + (u8a[2] << 8) + (u8a[3] << 16) + (u8a[4] * 0x1_00_00_00)];
+
+        case 6:
+          return [6, u8a[1] + (u8a[2] << 8) + (u8a[3] << 16) + ((u8a[4] + (u8a[5] << 8)) * 0x1_00_00_00)];
+
+        // 6 bytes data is the maximum, 48 bits (56 would overflow)
+        case 7:
+          return [7, u8a[1] + (u8a[2] << 8) + (u8a[3] << 16) + ((u8a[4] + (u8a[5] << 8) + (u8a[6] << 16)) * 0x1_00_00_00)];
+
+        // for anything else, we are above the actual MAX_SAFE_INTEGER - bail out
+        default:
+          throw new Error('Compact input is > Number.MAX_SAFE_INTEGER');
+      }
+    }
+  }
+}

package/src/compact/index.ts

@@ -0,0 +1,28 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @description
+ * Encoding and decoding of parity-codec compact numbers. The codec is created
+ * to take up the least amount of space for a specific number. It performs the
+ * same function as Length, however differs in that it uses a variable number of
+ * bytes to do the actual encoding. From the Rust implementation for compact
+ * encoding:
+ *
+ *     0b00 00 00 00 / 00 00 00 00 / 00 00 00 00 / 00 00 00 00
+ * (0 ... 2**6 - 1)    (u8)
+ *     xx xx xx 00
+ * (2**6 ... 2**14 - 1)  (u8, u16)  low LH high
+ *     yL yL yL 01 / yH yH yH yL
+ * (2**14 ... 2**30 - 1)  (u16, u32)  low LMMH high
+ *     zL zL zL 10 / zM zM zM zL / zM zM zM zM / zH zH zH zM
+ * (2**30 ... 2**536 - 1)  (u32, u64, u128, U256, U512, U520) straight LE-encoded
+ *     nn nn nn 11 [ / zz zz zz zz ]{4 + n}
+ *
+ * Note: we use *LOW BITS* of the LSB in LE encoding to encode the 2 bit key.
+ */
+
+export { compactAddLength } from './addLength.js';
+export { compactFromU8a, compactFromU8aLim } from './fromU8a.js';
+export { compactStripLength } from './stripLength.js';
+export { compactToU8a } from './toU8a.js';

package/src/compact/stripLength.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 { compactStripLength } from './index.js';
+
+describe('compactStripLength', (): void => {
+  it('correctly removes the length prefix', (): void => {
+    expect(
+      compactStripLength(Uint8Array.from([2 << 2, 12, 13]))
+    ).toEqual([
+      3,
+      Uint8Array.from([12, 13])
+    ]);
+  });
+});

package/src/compact/stripLength.ts

@@ -0,0 +1,26 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { compactFromU8a } from './fromU8a.js';
+
+/**
+ * @name compactStripLength
+ * @description Removes the length prefix, returning both the total length (including the value + compact encoding) and the decoded value with the correct length
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { compactStripLength } from '@pezkuwi/util';
+ *
+ * console.log(compactStripLength(new Uint8Array([2 << 2, 0xde, 0xad]))); // [2, Uint8Array[0xde, 0xad]]
+ * ```
+ */
+export function compactStripLength (input: Uint8Array): [number, Uint8Array] {
+  const [offset, length] = compactFromU8a(input);
+  const total = offset + length.toNumber();
+
+  return [
+    total,
+    input.subarray(offset, total)
+  ];
+}

package/src/compact/toU8a.spec.ts

@@ -0,0 +1,59 @@
+// 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 { compactToU8a } from './index.js';
+
+const TESTS: [output: string | Uint8Array, input: BN | number][] = [
+  // Rust tests
+  // Copied from https://github.com/paritytech/parity-codec/blob/master/src/codec.rs
+  ['00', new BN('0')],
+  ['fc', new BN('63')],
+  ['01 01', new BN('64')],
+  ['fd ff', new BN('16383')],
+  ['02 00 01 00', new BN('16384')],
+  ['fe ff ff ff', new BN('1073741823')],
+  ['03 00 00 00 40', new BN('1073741824')],
+  ['03 ff ff ff ff', new BN(`${1}${'0'.repeat(32)}`, 2).subn(1)],
+  ['07 00 00 00 00 01', new BN(`${1}${'0'.repeat(32)}`, 2)],
+  ['0b 00 00 00 00 00 01', new BN(`${1}${'0'.repeat(40)}`, 2)],
+  ['0f 00 00 00 00 00 00 01', new BN(`${1}${'0'.repeat(48)}`, 2)],
+  ['0f ff ff ff ff ff ff ff', new BN(`${1}${'0'.repeat(56)}`, 2).subn(1)],
+  ['13 00 00 00 00 00 00 00 01', new BN(`${1}${'0'.repeat(56)}`, 2)],
+  ['13 ff ff ff ff ff ff ff ff', new BN(`${1}${'0'.repeat(64)}`, 2).subn(1)],
+  // own tests
+  [new Uint8Array([18 << 2]), 18],
+  [new Uint8Array([0b11111100]), 63],
+  [new Uint8Array([0xbd, 0x01]), 111],
+  [new Uint8Array([0b11111101, 0b00000111]), 511],
+  [new Uint8Array([253, 127]), 0x1fff],
+  [new Uint8Array([254, 255, 3, 0]), 0xffff],
+  [new Uint8Array([3 + ((4 - 4) << 2), 249, 255, 255, 255]), 0xfffffff9],
+  [new Uint8Array([3 + ((6 - 4) << 2), 0x00, 0x40, 0x7a, 0x10, 0xf3, 0x5a]), new BN('00005af3107a4000', 16)],
+  [new Uint8Array([23, 52, 0x40, 0x7a, 0x10, 0xf3, 0x5a, 0, 0, 18]), new BN('1200005af3107a4034', 16)]
+];
+
+describe('encode', (): void => {
+  it('does not modify the original', (): void => {
+    const original = new BN(123456);
+
+    expect(compactToU8a(original)).toEqual(new Uint8Array([2, 137, 7, 0]));
+    expect(original.toString()).toEqual('123456');
+  });
+
+  describe('conversion tests', (): void => {
+    TESTS.forEach(([output, input], i): void => {
+      it(`#${i}: encodes ${input.toString()}`, (): void => {
+        expect(
+          compactToU8a(input)
+        ).toEqual(
+          output instanceof Uint8Array
+            ? output
+            : Uint8Array.from(output.split(' ').map((s) => parseInt(s, 16)))
+        );
+      });
+    });
+  });
+});

package/src/compact/toU8a.ts

@@ -0,0 +1,53 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { BN, BN_ONE, BN_TWO, bnToBn, bnToU8a } from '../bn/index.js';
+import { u8aConcatStrict } from '../u8a/index.js';
+
+const MAX_U8 = BN_TWO.pow(new BN(8 - 2)).isub(BN_ONE);
+const MAX_U16 = BN_TWO.pow(new BN(16 - 2)).isub(BN_ONE);
+const MAX_U32 = BN_TWO.pow(new BN(32 - 2)).isub(BN_ONE);
+const BL_16 = { bitLength: 16 };
+const BL_32 = { bitLength: 32 };
+
+/**
+ * @name compactToU8a
+ * @description Encodes a number into a compact representation
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { compactToU8a } from '@pezkuwi/util';
+ *
+ * console.log(compactToU8a(511, 32)); // Uint8Array([0b11111101, 0b00000111])
+ * ```
+ */
+export function compactToU8a (value: BN | bigint | number): Uint8Array {
+  const bn = bnToBn(value);
+
+  if (bn.lte(MAX_U8)) {
+    return new Uint8Array([bn.toNumber() << 2]);
+  } else if (bn.lte(MAX_U16)) {
+    return bnToU8a(bn.shln(2).iadd(BN_ONE), BL_16);
+  } else if (bn.lte(MAX_U32)) {
+    return bnToU8a(bn.shln(2).iadd(BN_TWO), BL_32);
+  }
+
+  const u8a = bnToU8a(bn);
+  let length = u8a.length;
+
+  // adjust to the minimum number of bytes
+  while (u8a[length - 1] === 0) {
+    length--;
+  }
+
+  if (length < 4) {
+    throw new Error('Invalid length, previous checks match anything less than 2^30');
+  }
+
+  return u8aConcatStrict([
+    // subtract 4 as minimum (also catered for in decoding)
+    new Uint8Array([((length - 4) << 2) + 0b11]),
+    u8a.subarray(0, length)
+  ]);
+}

package/src/compact/types.ts

@@ -0,0 +1,4 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+export type BitLength = 8 | 16 | 32 | 64 | 128 | 256;

package/src/detectPackage.spec.ts

@@ -0,0 +1,110 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { detectPackage, POLKADOTJS_DISABLE_ESM_CJS_WARNING_FLAG } from './detectPackage.js';
+
+describe('detectPackage', (): void => {
+  const PKG = '@pezkuwi/util';
+  const VER1 = '9.8.0-beta.45';
+  const VER2 = '9.7.1';
+  const VER3 = '9.6.1';
+  const PATH = '/Users/jaco/Projects/polkadot-js/api/node_modules/@pezkuwi/util';
+
+  const MISMATCH = `@pezkuwi/util has multiple versions, ensure that there is only one installed.
+Either remove and explicitly install matching versions or dedupe using your package manager.
+The following conflicting packages were found:
+\tesm ${VER1}\t<unknown>
+\tesm ${VER2}        \tnode_modules/@pezkuwi/api/node_modules/@pezkuwi/util`;
+
+  it('should not log the first time', (): void => {
+    const spy = jest.spyOn(console, 'warn');
+
+    detectPackage({ name: PKG, path: 'auto', type: 'esm', version: VER1 }, PATH);
+    expect(spy).not.toHaveBeenCalled();
+    spy.mockRestore();
+  });
+
+  it('should log the second time', (): void => {
+    const spy = jest.spyOn(console, 'warn');
+
+    detectPackage({ name: PKG, path: '/Users/jaco/Projects/polkadot-js/api/node_modules/@pezkuwi/api/node_modules/@pezkuwi/util', type: 'esm', version: VER2 });
+    expect(spy).toHaveBeenCalledWith(MISMATCH);
+    spy.mockRestore();
+  });
+
+  it('should allow for function use', (): void => {
+    const spy = jest.spyOn(console, 'warn');
+
+    detectPackage({ name: PKG, path: 'node_modules/@pezkuwi/util', type: 'cjs', version: VER3 }, () => PATH);
+    expect(spy).toHaveBeenCalledWith(`${MISMATCH}
+\tcjs ${VER3}        \tnode_modules/@pezkuwi/util`);
+    spy.mockRestore();
+  });
+});
+
+describe('detectPackageDeps', (): void => {
+  const DEP0 = { name: '@pezkuwi/keyring', path: 'auto', type: 'esm', version: '1.1.1' };
+  const DEP1 = { name: '@pezkuwi/util', path: 'auto', type: 'esm', version: '1.1.2' };
+  const DEP2 = { name: '@pezkuwi/util-crypto', path: 'auto', type: 'esm', version: '1.1.3' };
+  const DEP3 = { name: '@pezkuwi/networks', path: 'auto', type: 'esm', version: '1.1.1' };
+
+  it('should not log when no mismatches are found', (): void => {
+    const spy = jest.spyOn(console, 'warn');
+
+    detectPackage({ name: '@pezkuwi/one', path: 'auto', type: 'esm', version: '1.1.1' }, false, [DEP0, DEP3]);
+    expect(spy).not.toHaveBeenCalled();
+    spy.mockRestore();
+  });
+
+  it('should log when mismatches are found', (): void => {
+    const spy = jest.spyOn(console, 'warn');
+
+    detectPackage({ name: '@pezkuwi/two', path: 'auto', type: 'esm', version: '1.1.1' }, false, [DEP0, DEP1, DEP2, DEP3]);
+    expect(spy).toHaveBeenCalledWith(`@pezkuwi/two requires direct dependencies exactly matching version 1.1.1.
+Either remove and explicitly install matching versions or dedupe using your package manager.
+The following conflicting packages were found:
+\t1.1.2\t@pezkuwi/util
+\t1.1.3\t@pezkuwi/util-crypto`);
+    spy.mockRestore();
+  });
+});
+
+describe('detectPackageEsmCjsNoWarnings', (): void => {
+  const PKG = '@pezkuwi/wasm-crypto';
+  const VER1 = '9.8.0-beta.45';
+  const PATH = '/Users/jaco/Projects/polkadot-js/api/node_modules/@pezkuwi/api/node_modules/@pezkuwi/wasm-crypto';
+
+  it('should not log when there are concurrent esm and cjs versions of the same package with the same version number and warnings are disabled', (): void => {
+    const spy = jest.spyOn(console, 'warn');
+    const pkgEsm = { name: PKG, path: PATH, type: 'esm', version: VER1 };
+    const pkgCjs = { name: PKG, path: `${PATH}/cjs`, type: 'cjs', version: VER1 };
+
+    process.env[POLKADOTJS_DISABLE_ESM_CJS_WARNING_FLAG] = '1';
+    detectPackage(pkgEsm, false, []);
+    detectPackage(pkgCjs, false, []);
+
+    expect(spy).not.toHaveBeenCalled();
+    spy.mockRestore();
+  });
+});
+
+describe('detectPackageEsmCjs', (): void => {
+  const PKG = '@pezkuwi/wasm-crypto-wasm';
+  const VER1 = '9.8.0-beta.45';
+  const PATH = '/Users/jaco/Projects/polkadot-js/api/node_modules/@pezkuwi/api/node_modules/@pezkuwi/wasm-crypto-wasm';
+
+  it('should log when there are concurrent esm and cjs versions of the same package with the same version number and warnings are not disabled', (): void => {
+    const spy = jest.spyOn(console, 'warn');
+    const pkgEsm = { name: PKG, path: PATH, type: 'esm', version: VER1 };
+    const pkgCjs = { name: PKG, path: `${PATH}/cjs`, type: 'cjs', version: VER1 };
+
+    process.env[POLKADOTJS_DISABLE_ESM_CJS_WARNING_FLAG] = undefined;
+    detectPackage(pkgEsm, false, []);
+    detectPackage(pkgCjs, false, []);
+
+    expect(spy).toHaveBeenCalled();
+    spy.mockRestore();
+  });
+});

package/src/detectPackage.ts

@@ -0,0 +1,138 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { xglobal } from '@pezkuwi/x-global';
+
+import { isFunction } from './is/function.js';
+
+type This = typeof globalThis;
+
+interface VersionPath {
+  path: string;
+  type: string;
+  version: string;
+}
+
+interface PackageInfo extends VersionPath {
+  name: string;
+}
+
+interface PjsChecks extends This {
+  __polkadotjs: Record<string, VersionPath[]>;
+}
+
+type PjsGlobal = This & PjsChecks & Record<string, unknown>;
+type FnString = () => string | undefined;
+
+const DEDUPE = 'Either remove and explicitly install matching versions or dedupe using your package manager.\nThe following conflicting packages were found:';
+
+export const POLKADOTJS_DISABLE_ESM_CJS_WARNING_FLAG = 'POLKADOTJS_DISABLE_ESM_CJS_WARNING';
+
+/** @internal */
+function getEntry (name: string): VersionPath[] {
+  const _global = xglobal as PjsGlobal;
+
+  if (!_global.__polkadotjs) {
+    _global.__polkadotjs = {};
+  }
+
+  if (!_global.__polkadotjs[name]) {
+    _global.__polkadotjs[name] = [];
+  }
+
+  return _global.__polkadotjs[name];
+}
+
+/** @internal */
+function formatDisplay <T extends { version: string }> (all: T[], fmt: (version: string, data: T) => string[]): string {
+  let max = 0;
+
+  for (let i = 0, count = all.length; i < count; i++) {
+    max = Math.max(max, all[i].version.length);
+  }
+
+  return all
+    .map((d) => `\t${fmt(d.version.padEnd(max), d).join('\t')}`)
+    .join('\n');
+}
+
+/** @internal */
+function formatInfo (version: string, { name }: PackageInfo): string[] {
+  return [
+    version,
+    name
+  ];
+}
+
+/** @internal */
+function formatVersion (version: string, { path, type }: VersionPath): string[] {
+  let extracted: string;
+
+  if (path && path.length >= 5) {
+    const nmIndex = path.indexOf('node_modules');
+
+    extracted = nmIndex === -1
+      ? path
+      : path.substring(nmIndex);
+  } else {
+    extracted = '<unknown>';
+  }
+
+  return [
+    `${`${type || ''}`.padStart(3)} ${version}`,
+    extracted
+  ];
+}
+
+/** @internal */
+function getPath (infoPath?: string, pathOrFn?: FnString | string | false | null): string {
+  if (infoPath) {
+    return infoPath;
+  } else if (isFunction(pathOrFn)) {
+    try {
+      return pathOrFn() || '';
+    } catch {
+      return '';
+    }
+  }
+
+  return pathOrFn || '';
+}
+
+/** @internal */
+function warn <T extends { version: string }> (pre: string, all: T[], fmt: (version: string, data: T) => string[]): void {
+  console.warn(`${pre}\n${DEDUPE}\n${formatDisplay(all, fmt)}`);
+}
+
+/**
+ * @name detectPackage
+ * @summary Checks that a specific package is only imported once
+ * @description A `@pezkuwi/*` version detection utility, checking for one occurrence of a package in addition to checking for dependency versions.
+ */
+export function detectPackage ({ name, path, type, version }: PackageInfo, pathOrFn?: FnString | string | false | null, deps: PackageInfo[] = []): void {
+  if (!name.startsWith('@pezkuwi')) {
+    throw new Error(`Invalid package descriptor ${name}`);
+  }
+
+  const entry = getEntry(name);
+
+  entry.push({ path: getPath(path, pathOrFn), type, version });
+
+  // if we have more than one entry at DIFFERENT version types then warn. If there is
+  // more than one entry at the same version and ESM/CJS dual warnings are disabled,
+  // then do not display warnings
+  const entriesSameVersion = entry.every((e) => e.version === version);
+  const esmCjsWarningDisabled = xglobal.process?.env?.[POLKADOTJS_DISABLE_ESM_CJS_WARNING_FLAG] === '1';
+  const multipleEntries = entry.length !== 1;
+  const disableWarnings = esmCjsWarningDisabled && entriesSameVersion;
+
+  if (multipleEntries && !disableWarnings) {
+    warn(`${name} has multiple versions, ensure that there is only one installed.`, entry, formatVersion);
+  } else {
+    const mismatches = deps.filter((d) => d && d.version !== version);
+
+    if (mismatches.length) {
+      warn(`${name} requires direct dependencies exactly matching version ${version}.`, mismatches, formatInfo);
+    }
+  }
+}

package/src/extractTime.spec.ts

@@ -0,0 +1,21 @@
+// Copyright 2017-2025 @pezkuwi/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { extractTime } from './index.js';
+
+describe('extractTime', (): void => {
+  const milliseconds = 1e9 + 123;
+
+  it('extracts time components correctly', (): void => {
+    expect(extractTime(milliseconds))
+      .toEqual({
+        days: 11,
+        hours: 13,
+        milliseconds: 123,
+        minutes: 46,
+        seconds: 40
+      });
+  });
+});