@pezkuwi/util 14.0.1

package/src/string/lowerFirst.ts

@@ -0,0 +1,46 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { AnyString } from '../types.js';
+
+import { CC_TO_LO, CC_TO_UP } from './camelCase.js';
+
+/** @internal */
+function converter (map: readonly string[]): (value?: AnyString | null) => string {
+  return (value?: AnyString | null): string =>
+    value
+      ? map[value.charCodeAt(0)] + value.slice(1)
+      : '';
+}
+
+/**
+ * @name stringLowerFirst
+ * @summary Lowercase the first letter of a string
+ * @description
+ * Lowercase the first letter of a string
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { stringLowerFirst } from '@pezkuwi/util';
+ *
+ * stringLowerFirst('ABC'); // => 'aBC'
+ * ```
+ */
+export const stringLowerFirst = /*#__PURE__*/ converter(CC_TO_LO);
+
+/**
+ * @name stringUpperFirst
+ * @summary Uppercase the first letter of a string
+ * @description
+ * Lowercase the first letter of a string
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { stringUpperFirst } from '@pezkuwi/util';
+ *
+ * stringUpperFirst('abc'); // => 'Abc'
+ * ```
+ */
+export const stringUpperFirst = /*#__PURE__*/ converter(CC_TO_UP);

package/src/string/pascalCase.spec.ts

@@ -0,0 +1,26 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+import { stringPascalCase } from './index.js';
+
+describe('stringPascalCase', (): void => {
+  it('works correctly', (): void => {
+    expect(
+      stringPascalCase('Snake_case-something  spaced')
+    ).toBe('SnakeCaseSomethingSpaced');
+  });
+
+  it('works correctly for String (class)', (): void => {
+    expect(
+      stringPascalCase(String('foo_bar--  __baz Bob'))
+    ).toBe('FooBarBazBob');
+  });
+
+  it('adjusts all-uppercase + digits', (): void => {
+    expect(
+      stringPascalCase('UUID64')
+    ).toEqual('Uuid64');
+  });
+});

package/src/string/shorten.spec.ts

@@ -0,0 +1,38 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+import { stringShorten } from './index.js';
+
+describe('stringShorten', (): void => {
+  it('returns the value as-is when <= maxLength', (): void => {
+    expect(
+      stringShorten('0123456789', 4)
+    ).toEqual('0123456789');
+  });
+
+  it('returns the shortened value when > maxLength', (): void => {
+    expect(
+      stringShorten('0123456789', 3)
+    ).toEqual('012…789');
+  });
+
+  it('returns the shortened value when > maxLength (String)', (): void => {
+    expect(
+      stringShorten(String('0123456789'), 3)
+    ).toEqual('012…789');
+  });
+
+  it('returns the value as-is when <= maxLength (defaults)', (): void => {
+    expect(
+      stringShorten('012345', 4)
+    ).toEqual('012345');
+  });
+
+  it('returns the shortened value when > maxLength (defaults)', (): void => {
+    expect(
+      stringShorten('01234567890123456789')
+    ).toEqual('012345…456789');
+  });
+});

package/src/string/shorten.ts

@@ -0,0 +1,24 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { AnyString } from '../types.js';
+
+/**
+ * @name stringShorten
+ * @summary Returns a string with maximum length
+ * @description
+ * Checks the string against the `prefixLength`, if longer than double this, shortens it by placing `..` in the middle of it
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { stringShorten } from '@pezkuwi/util';
+ *
+ * stringShorten('1234567890', 2); // => 12..90
+ * ```
+ */
+export function stringShorten (value: AnyString, prefixLength = 6): string {
+  return value.length <= 2 + 2 * prefixLength
+    ? value.toString()
+    : `${value.substring(0, prefixLength)}…${value.slice(-prefixLength)}`;
+}

package/src/string/toHex.spec.ts

@@ -0,0 +1,26 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+import { stringToHex } from './index.js';
+
+describe('hexToString', (): void => {
+  it('converts an empty to ""', (): void => {
+    expect(
+      stringToHex()
+    ).toEqual('0x');
+  });
+
+  it('converts to a hex from string', (): void => {
+    expect(
+      stringToHex('hello')
+    ).toEqual('0x68656c6c6f');
+  });
+
+  it('converts to a hex from String', (): void => {
+    expect(
+      stringToHex(String('hello'))
+    ).toEqual('0x68656c6c6f');
+  });
+});

package/src/string/toHex.ts

@@ -0,0 +1,27 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { AnyString, HexString } from '../types.js';
+
+import { u8aToHex } from '../u8a/toHex.js';
+import { stringToU8a } from './toU8a.js';
+
+/**
+ * @name stringToHex
+ * @summary Creates a hex string from a utf-8 string
+ * @description
+ * String input values return the actual encoded hex value.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { stringToHex } from '@pezkuwi/util';
+ *
+ * stringToU8a('hello'); // 0x68656c6c6f
+ * ```
+ */
+export function stringToHex (value?: AnyString): HexString {
+  return u8aToHex(
+    stringToU8a(value)
+  );
+}

package/src/string/toU8a.spec.ts

@@ -0,0 +1,31 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+import { stringToU8a } from '../index.js';
+
+const RUSS_HELLO = new Uint8Array([208, 159, 209, 128, 208, 184, 208, 178, 208, 181, 209, 130, 44, 32, 208, 188, 208, 184, 209, 128, 33]);
+
+describe('stringToU8a', (): void => {
+  it('decodes to an empty string for undefined/null', (): void => {
+    expect(
+      stringToU8a()
+    ).toEqual(new Uint8Array());
+    expect(
+      stringToU8a(null)
+    ).toEqual(new Uint8Array());
+  });
+
+  it('encodes the string correctly', (): void => {
+    expect(
+      stringToU8a('Привет, мир!')
+    ).toEqual(RUSS_HELLO);
+  });
+
+  it('encodes the string correctly (String)', (): void => {
+    expect(
+      stringToU8a(String('Привет, мир!'))
+    ).toEqual(RUSS_HELLO);
+  });
+});

package/src/string/toU8a.ts

@@ -0,0 +1,28 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { AnyString } from '../types.js';
+
+import { TextEncoder } from '@pezkuwi/x-textencoder';
+
+const encoder = new TextEncoder();
+
+/**
+ * @name stringToU8a
+ * @summary Creates a Uint8Array object from a utf-8 string.
+ * @description
+ * String input values return the actual encoded `UInt8Array`. `null` or `undefined` values returns an empty encoded array.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { stringToU8a } from '@pezkuwi/util';
+ *
+ * stringToU8a('hello'); // [0x68, 0x65, 0x6c, 0x6c, 0x6f]
+ * ```
+ */
+export function stringToU8a (value?: AnyString | null): Uint8Array {
+  return value
+    ? encoder.encode(value.toString())
+    : new Uint8Array();
+}

package/src/string/upperFirst.spec.ts

@@ -0,0 +1,41 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+import { perf } from '../test/index.js';
+import { stringUpperFirst } from './index.js';
+
+describe('stringUpperFirst', (): void => {
+  it("uppers the first letter if it's a capital letter", (): void => {
+    expect(
+      stringUpperFirst('ABC')
+    ).toBe('ABC');
+  });
+
+  it("uppers the first letter if it's a lowercase letter", (): void => {
+    expect(
+      stringUpperFirst('abc')
+    ).toBe('Abc');
+  });
+
+  it("uppers the first letter if it's a lowercase letter (String)", (): void => {
+    expect(
+      stringUpperFirst(String('abc'))
+    ).toBe('Abc');
+  });
+
+  it('returns undefined as empty', (): void => {
+    expect(
+      stringUpperFirst()
+    ).toBe('');
+  });
+
+  it('returns null as empty', (): void => {
+    expect(
+      stringUpperFirst(null)
+    ).toBe('');
+  });
+
+  perf('stringUpperFirst', 1_000_000, [['helloWorldSomething']], stringUpperFirst);
+});

package/src/stringify.spec.ts

@@ -0,0 +1,33 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+import { BN } from './bn/index.js';
+import { stringify } from './stringify.js';
+
+describe('stringify', (): void => {
+  it('stringifies a BigInt', (): void => {
+    expect(
+      stringify(1234n)
+    ).toEqual('"1234"');
+  });
+
+  it('stringifies an array of values', (): void => {
+    expect(
+      stringify(['a', 1, 2n, new BN(69)])
+    ).toEqual('["a",1,"2","45"]');
+  });
+
+  it('stringifies an array of values (with spaces)', (): void => {
+    expect(
+      stringify(['a', 1, 2n, new BN(3)], 2)
+    ).toEqual('[\n  "a",\n  1,\n  "2",\n  "03"\n]');
+  });
+
+  it('stringifies a nested object', (): void => {
+    expect(
+      stringify({ a: 'a', b: 1, c: { d: 2n, e: new BN(3) } })
+    ).toEqual('{"a":"a","b":1,"c":{"d":"2","e":"03"}}');
+  });
+});

package/src/stringify.ts

@@ -0,0 +1,20 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { isBigInt } from './is/bigInt.js';
+
+/** @internal */
+function replacer (_: unknown, v: unknown): unknown {
+  return isBigInt(v)
+    ? v.toString()
+    : v;
+}
+
+/**
+ * @name stringify
+ * @summary Performs a JSON.stringify, with BigInt handling
+ * @description A wrapper for JSON.stringify that handles BigInt values transparently, converting them to string. No differences from the native JSON.stringify function otherwise.
+ */
+export function stringify (value: unknown, space?: string | number): string {
+  return JSON.stringify(value, replacer, space);
+}

package/src/test/index.ts

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

package/src/test/performance.ts

@@ -0,0 +1,92 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+/* global it, expect */
+
+import { formatDecimal, formatNumber, stringify } from '../index.js';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type ExecFn = (...params: any[]) => unknown;
+
+const NUM_PAD = 16;
+const PRE_PAD = 32;
+
+function loop (exec: ExecFn, count: number, inputs: readonly unknown[][]): [number, unknown[]] {
+  const start = performance.now();
+  const results = new Array<unknown>(inputs.length);
+
+  for (let i = 0; i < count; i++) {
+    const result = exec(...inputs[i % inputs.length]);
+
+    if (i < inputs.length) {
+      results[i] = result;
+    }
+  }
+
+  return [performance.now() - start, results];
+}
+
+export function formatFixed (value: number): string {
+  const [a, b] = value.toFixed(2).split('.');
+
+  return [formatDecimal(a), b].join('.');
+}
+
+export function formatOps (count: number, time: number): string {
+  const micro = (time * 1000) / count;
+  const ops = 1_000_000 / micro;
+
+  return `
+${formatFixed(ops).padStart(NUM_PAD + PRE_PAD + 1)} ops/s
+${formatFixed(micro).padStart(NUM_PAD + PRE_PAD + 1)} μs/op`;
+}
+
+export function perf (name: string, count: number, inputs: readonly unknown[][], exec: ExecFn, withLog?: boolean): void {
+  const test = process.env['GITHUB_REPOSITORY']
+    ? it.skip
+    : it;
+
+  test(`performance: ${name}`, (): void => {
+    const [time, results] = loop(exec, count, inputs);
+
+    console.error(`
+performance run for ${name} completed with ${formatNumber(count)} iterations.
+
+${`${name}:`.padStart(PRE_PAD)} ${time.toFixed(2).padStart(NUM_PAD)} ms${formatOps(count, time)}
+`);
+
+    if (withLog) {
+      console.log(results);
+    }
+  });
+}
+
+export function perfCmp (name: string, [first, second]: [string, string], count: number, inputs: readonly unknown[][], exec: ExecFn): void {
+  const test = process.env['GITHUB_REPOSITORY']
+    ? it.skip
+    : it;
+
+  test(`performance: ${name}`, (): void => {
+    const [[t1, r1], [t2, r2]] = [false, true].map((flag) =>
+      loop(exec, count, inputs.map((values) =>
+        [...values, flag]
+      ))
+    );
+
+    console.error(`
+performance run for ${name} completed with ${formatNumber(count)} iterations.
+
+${`${first}:`.padStart(PRE_PAD)} ${t1.toFixed(2).padStart(NUM_PAD)} ms ${t1 < t2 ? '(fastest)' : `(slowest, ${(t1 / t2).toFixed(2)}x)`}${formatOps(count, t1)}
+
+${`${second}:`.padStart(PRE_PAD)} ${t2.toFixed(2).padStart(NUM_PAD)} ms ${t1 > t2 ? '(fastest)' : `(slowest, ${(t2 / t1).toFixed(2)}x)`}${formatOps(count, t2)}
+`);
+
+    expect(
+      r1.filter((_, i) =>
+        stringify(r1[i]) !== stringify(r2[i])
+      )
+    ).toHaveLength(0);
+  });
+}

package/src/types.ts

@@ -0,0 +1,100 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { BN } from './bn/bn.js';
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/** An interface that defines an actual JS class */
+export interface Class<T = any, A extends unknown[] = any[]> {
+  prototype: T;
+
+  new (...args: A): T;
+
+  hasOwnProperty (prop: string): boolean;
+  isPrototypeOf (other: unknown): boolean;
+}
+
+// @deprecated Use Class<T, A> instead
+export type Constructor<T = any, A extends unknown[] = any[]> = Class<T, A>;
+
+export interface ToBigInt {
+  toBigInt: () => bigint;
+}
+
+export interface ToBn {
+  toBn: () => BN;
+}
+
+export interface SiDef {
+  power: number;
+  text: string;
+  value: string;
+}
+
+export interface Logger {
+  debug: (...values: unknown[]) => void;
+  error: (...values: unknown[]) => void;
+  log: (...values: unknown[]) => void;
+  noop: (...values: unknown[]) => void;
+  warn: (...values: unknown[]) => void;
+}
+
+export interface ToBnOptions {
+  /** Convert in LE format */
+  isLe?: boolean;
+  /** Number is signed, apply two's complement */
+  isNegative?: boolean;
+}
+
+export interface NumberOptions extends ToBnOptions {
+  /** Limit to the specified bitLength, despite input length */
+  bitLength?: number;
+}
+
+export interface Time {
+  days: number;
+  hours: number;
+  minutes: number;
+  seconds: number;
+  milliseconds: number;
+}
+
+export type Memoized<F> = F & {
+  unmemoize: (...args: unknown[]) => void;
+}
+
+// eslint-disable-next-line @typescript-eslint/ban-types
+export type AnyString = string | String;
+
+export type HexDigit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | 'a' | 'b' | 'c' | 'd' | 'e' | 'f';
+
+// One day when template strings support regex, we can improve this
+export type HexString = `0x${string}`;
+
+// BufferObject interface compatible with Buffer since we don't want to require
+// references to the Buffer types from the node typings
+//
+// Caveat: the references still do sneak in in the d.ts files, specifically
+// inside u8a/toBuffer & is/buffer (but not in compiled outputs)
+export interface BufferObject extends Uint8Array {
+  // Possibly used externally via type imports
+  equals: (otherBuffer: Uint8Array) => boolean;
+  // As used in is/buffer
+  readDoubleLE: (offset?: number) => number;
+}
+
+// We define a scappy low-level interface to mock Buffer
+// (this removes the need for the node typings in built bundles)
+export interface BufferClass extends Class<BufferObject> {
+  // As used in u8a/toBuffer
+  from: <T = BufferObject>(value: unknown) => T;
+  // As used in is/buffer
+  isBuffer: (value: unknown) => boolean;
+}
+
+export type U8aLike = number[] | Uint8Array | AnyString;
+
+export interface Observable {
+  next: (...params: unknown[]) => unknown;
+}

package/src/u8a/cmp.spec.ts

@@ -0,0 +1,62 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@polkadot/dev-test/globals.d.ts" />
+
+import { perf } from '../test/index.js';
+import { u8aCmp } from './index.js';
+
+const ltest = new Uint8Array(32768);
+const stest = new Uint8Array(256);
+const ztest = new Uint8Array(64);
+
+for (let i = 0, count = ltest.length; i < count; i++) {
+  if (i < ztest.length) {
+    ztest[i] = i % 256;
+  }
+
+  if (i < stest.length) {
+    stest[i] = i % 256;
+  }
+
+  ltest[i] = i % 256;
+}
+
+describe('u8aCmp', (): void => {
+  it('has the same result as localCompare (equal length)', (): void => {
+    const a = 'test abc';
+    const b = 'test def';
+
+    expect(
+      u8aCmp(a, b)
+    ).toEqual(a.localeCompare(b));
+    expect(
+      u8aCmp(b, a)
+    ).toEqual(b.localeCompare(a));
+  });
+
+  it('has the same result as localCompare (diff length)', (): void => {
+    const a = 'test';
+    const b = 'test abc';
+
+    expect(
+      u8aCmp(a, b)
+    ).toEqual(a.localeCompare(b));
+    expect(
+      u8aCmp(b, a)
+    ).toEqual(b.localeCompare(a));
+  });
+
+  it('compares between string and Uint8Array', (): void => {
+    expect(
+      u8aCmp(
+        '0x12345678',
+        new Uint8Array([0x12, 0x34, 0x56, 0x78])
+      )
+    ).toEqual(0);
+  });
+
+  perf('u8aCmp (64 cmp)', 100_000, [[ztest, ztest]], u8aCmp);
+  perf('u8aCmp (256 cmp)', 50_000, [[stest, stest]], u8aCmp);
+  perf('u8aCmp (32k cmp)', 500, [[ltest, ltest]], u8aCmp);
+});

package/src/u8a/cmp.ts

@@ -0,0 +1,50 @@
+// Copyright 2017-2025 @polkadot/util authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { u8aToU8a } from './toU8a.js';
+
+/**
+ * @name u8aCmp
+ * @summary Compares two Uint8Arrays for sorting.
+ * @description
+ * For `UInt8Array` (or hex string) input values returning -1, 0 or +1
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { u8aCmp } from '@pezkuwi/util';
+ *
+ * u8aCmp(new Uint8Array([0x67, 0x65]), new Uint8Array([0x68, 0x65])); // -1
+ * u8aCmp(new Uint8Array([0x68, 0x65]), new Uint8Array([0x68, 0x65])); // 0
+ * u8aCmp(new Uint8Array([0x69, 0x65]), new Uint8Array([0x68, 0x65])); // +1
+ * ```
+ */
+export function u8aCmp (a: string | Uint8Array, b: string | Uint8Array): number {
+  const u8aa = u8aToU8a(a);
+  const u8ab = u8aToU8a(b);
+  let i = 0;
+
+  while (true) {
+    const overA = i >= u8aa.length;
+    const overB = i >= u8ab.length;
+
+    if (overA && overB) {
+      // both ends reached
+      return 0;
+    } else if (overA) {
+      // a has no more data, b has data
+      return -1;
+    } else if (overB) {
+      // b has no more data, a has data
+      return 1;
+    } else if (u8aa[i] !== u8ab[i]) {
+      // the number in this index doesn't match
+      // (we don't use u8aa[i] - u8ab[i] since that doesn't match with localeCompare)
+      return u8aa[i] > u8ab[i]
+        ? 1
+        : -1;
+    }
+
+    i++;
+  }
+}