@pezkuwi/util 14.0.5 → 14.0.6

package/build-deno/string/toU8a.ts

@@ -0,0 +1,26 @@
+
+import type { AnyString } from '../types.ts';
+
+import { TextEncoder } from 'https://deno.land/x/pezkuwi/x-textencoder/mod.ts';
+
+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 'https://deno.land/x/pezkuwi/util/mod.ts';
+ *
+ * stringToU8a('hello'); // [0x68, 0x65, 0x6c, 0x6c, 0x6f]
+ * ```
+ */
+export function stringToU8a (value?: AnyString | null): Uint8Array {
+  return value
+    ? encoder.encode(value.toString())
+    : new Uint8Array();
+}

package/build-deno/stringify.ts

@@ -0,0 +1,18 @@
+
+import { isBigInt } from './is/bigInt.ts';
+
+/** @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/build-deno/test/index.ts

@@ -0,0 +1,2 @@
+
+export { perf, perfCmp } from './performance.ts';

package/build-deno/test/performance.ts

@@ -0,0 +1,88 @@
+
+
+/* global it, expect */
+
+import { formatDecimal, formatNumber, stringify } from '../index.ts';
+
+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/build-deno/types.ts

@@ -0,0 +1,90 @@
+import { Buffer } from 'node:buffer';
+
+
+import type { BN } from './bn/bn.ts';
+
+/* 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;
+}
+
+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;
+}
+
+export type AnyString = string | String;
+
+export type HexDigit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | 'a' | 'b' | 'c' | 'd' | 'e' | 'f';
+
+export type HexString = `0x${string}`;
+
+export interface BufferObject extends Uint8Array {
+  // Possibly used externally via type imports
+  equals: (otherBuffer: Uint8Array) => boolean;
+  // As used in is/buffer
+  readDoubleLE: (offset?: number) => number;
+}
+
+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/build-deno/u8a/cmp.ts

@@ -0,0 +1,48 @@
+
+import { u8aToU8a } from './toU8a.ts';
+
+/**
+ * @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 'https://deno.land/x/pezkuwi/util/mod.ts';
+ *
+ * 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++;
+  }
+}

package/build-deno/u8a/concat.ts

@@ -0,0 +1,58 @@
+
+import type { U8aLike } from '../types.ts';
+
+import { u8aToU8a } from './toU8a.ts';
+
+/**
+ * @name u8aConcat
+ * @summary Creates a concatenated Uint8Array from the inputs.
+ * @description
+ * Concatenates the input arrays into a single `UInt8Array`.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { { u8aConcat } from 'https://deno.land/x/pezkuwi/util/mod.ts';
+ *
+ * u8aConcat(
+ *   new Uint8Array([1, 2, 3]),
+ *   new Uint8Array([4, 5, 6])
+ * ); // [1, 2, 3, 4, 5, 6]
+ * ```
+ */
+export function u8aConcat (...list: readonly U8aLike[]): Uint8Array {
+  const count = list.length;
+  const u8as = new Array<Uint8Array>(count);
+  let length = 0;
+
+  for (let i = 0; i < count; i++) {
+    u8as[i] = u8aToU8a(list[i]);
+    length += u8as[i].length;
+  }
+
+  return u8aConcatStrict(u8as, length);
+}
+
+/**
+ * @name u8aConcatStrict
+ * @description A strict version of [[u8aConcat]], accepting only Uint8Array inputs
+ */
+export function u8aConcatStrict (u8as: readonly Uint8Array[], length = 0): Uint8Array {
+  const count = u8as.length;
+  let offset = 0;
+
+  if (!length) {
+    for (let i = 0; i < count; i++) {
+      length += u8as[i].length;
+    }
+  }
+
+  const result = new Uint8Array(length);
+
+  for (let i = 0; i < count; i++) {
+    result.set(u8as[i], offset);
+    offset += u8as[i].length;
+  }
+
+  return result;
+}

package/build-deno/u8a/concatBuffer.ts

@@ -0,0 +1,34 @@
+import { Buffer } from 'node:buffer';
+
+
+import type { U8aLike } from '../types.ts';
+
+import { u8aToU8a } from './toU8a.ts';
+
+/**
+ * @name u8aConcat
+ * @summary Creates a concatenated Uint8Array from the inputs.
+ * @description
+ * Concatenates the input arrays into a single `UInt8Array`.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { { u8aConcat } from 'https://deno.land/x/pezkuwi/util/mod.ts';
+ *
+ * u8aConcat(
+ *   new Uint8Array([1, 2, 3]),
+ *   new Uint8Array([4, 5, 6])
+ * ); // [1, 2, 3, 4, 5, 6]
+ * ```
+ */
+export function u8aConcat (...list: readonly U8aLike[]): Uint8Array {
+  const count = list.length;
+  const u8as = new Array<Uint8Array>(count);
+
+  for (let i = 0; i < count; i++) {
+    u8as[i] = u8aToU8a(list[i]);
+  }
+
+  return Uint8Array.from(Buffer.concat(u8as));
+}

package/build-deno/u8a/empty.ts

@@ -0,0 +1,20 @@
+
+/**
+ * @name u8aEmpty
+ * @summary Tests for a `Uint8Array` for emptyness
+ * @description
+ * Checks to see if the input `Uint8Array` has zero length or contains all 0 values.
+ */
+export function u8aEmpty (value: Uint8Array): boolean {
+  const len = value.length | 0;
+
+  // on smaller sizes, the byte-by-byte compare is faster than allocating
+  // another object for DataView (on very large arrays the DataView is faster)
+  for (let i = 0; i < len; i++) {
+    if (value[i] | 0) {
+      return false;
+    }
+  }
+
+  return true;
+}

package/build-deno/u8a/eq.ts

@@ -0,0 +1,44 @@
+
+import { u8aToU8a } from './toU8a.ts';
+
+/**
+ * @name u8aEq
+ * @summary Compares two Uint8Arrays for equality.
+ * @description
+ * For `UInt8Array` (or hex string) input values true if there is a match.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { u8aEq } from 'https://deno.land/x/pezkuwi/util/mod.ts';
+ *
+ * u8aEq(new Uint8Array([0x68, 0x65]), new Uint8Array([0x68, 0x65])); // true
+ * ```
+ */
+export function u8aEq (a: string | Uint8Array, b: string | Uint8Array): boolean {
+  const u8aa = u8aToU8a(a);
+  const u8ab = u8aToU8a(b);
+
+  if (u8aa.length === u8ab.length) {
+    const dvA = new DataView(u8aa.buffer, u8aa.byteOffset);
+    const dvB = new DataView(u8ab.buffer, u8ab.byteOffset);
+    const mod = (u8aa.length % 4) | 0;
+    const length = (u8aa.length - mod) | 0;
+
+    for (let i = 0; i < length; i += 4) {
+      if (dvA.getUint32(i) !== dvB.getUint32(i)) {
+        return false;
+      }
+    }
+
+    for (let i = length, count = u8aa.length; i < count; i++) {
+      if (u8aa[i] !== u8ab[i]) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  return false;
+}

package/build-deno/u8a/fixLength.ts

@@ -0,0 +1,32 @@
+
+/**
+ * @name u8aFixLength
+ * @summary Shifts a Uint8Array to a specific bitLength
+ * @description
+ * Returns a uint8Array 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.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { u8aFixLength } from 'https://deno.land/x/pezkuwi/util/mod.ts';
+ *
+ * u8aFixLength('0x12') // => 0x12
+ * u8aFixLength('0x12', 16) // => 0x0012
+ * u8aFixLength('0x1234', 8) // => 0x12
+ * ```
+ */
+export function u8aFixLength (value: Uint8Array, bitLength = -1, atStart = false): Uint8Array {
+  const byteLength = Math.ceil(bitLength / 8);
+
+  if (bitLength === -1 || value.length === byteLength) {
+    return value;
+  } else if (value.length > byteLength) {
+    return value.subarray(0, byteLength);
+  }
+
+  const result = new Uint8Array(byteLength);
+
+  result.set(value, atStart ? 0 : (byteLength - value.length));
+
+  return result;
+}

package/build-deno/u8a/index.ts

@@ -0,0 +1,22 @@
+import { Buffer } from 'node:buffer';
+
+
+/**
+ * @summary Utility methods to convert to and from `Uint8Array` objects
+ */
+
+export { u8aCmp } from './cmp.ts';
+export { u8aConcat, u8aConcatStrict } from './concat.ts';
+export { u8aEmpty } from './empty.ts';
+export { u8aEq } from './eq.ts';
+export { u8aFixLength } from './fixLength.ts';
+export { u8aSorted } from './sorted.ts';
+export { u8aToBigInt } from './toBigInt.ts';
+export { u8aToBn } from './toBn.ts';
+export { u8aToBuffer } from './toBuffer.ts';
+export { u8aToFloat } from './toFloat.ts';
+export { u8aToHex } from './toHex.ts';
+export { u8aToNumber } from './toNumber.ts';
+export { u8aToString } from './toString.ts';
+export { u8aToU8a } from './toU8a.ts';
+export { U8A_WRAP_ETHEREUM, U8A_WRAP_POSTFIX, U8A_WRAP_PREFIX, u8aIsWrapped, u8aUnwrapBytes, u8aWrapBytes } from './wrap.ts';

package/build-deno/u8a/sorted.ts

@@ -0,0 +1,20 @@
+
+import { u8aCmp } from './cmp.ts';
+
+/**
+ * @name u8aSorted
+ * @summary Sorts an array of Uint8Arrays
+ * @description
+ * For input `UInt8Array[]` return the sorted result
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import { u8aSorted} from 'https://deno.land/x/pezkuwi/util/mod.ts';
+ *
+ * u8aSorted([new Uint8Array([0x69]), new Uint8Array([0x68])]); // [0x68, 0x69]
+ * ```
+ */
+export function u8aSorted (u8as: Uint8Array[]): Uint8Array[] {
+  return u8as.sort(u8aCmp);
+}

package/build-deno/u8a/toBigInt.ts

@@ -0,0 +1,98 @@
+
+import type { ToBnOptions } from '../types.ts';
+
+import { BigInt } from 'https://deno.land/x/pezkuwi/x-bigint/mod.ts';
+
+import { _1n } from '../bi/consts.ts';
+
+const U8_MAX = BigInt(256);
+const U16_MAX = BigInt(256 * 256);
+const U64_MAX = BigInt('0x10000000000000000');
+
+/**
+ * @name u8aToBigInt
+ * @summary Creates a BigInt from a Uint8Array object.
+ */
+export function u8aToBigInt (value: Uint8Array, { isLe = true, isNegative = false }: ToBnOptions = {}): bigint {
+  // slice + reverse is expensive, however SCALE is LE by default so this is the path
+  // we are most interested in (the BE is added for the sake of being comprehensive)
+  if (!isLe) {
+    value = value.slice().reverse();
+  }
+
+  const count = value.length;
+
+  if (isNegative && count && (value[count - 1] & 0x80)) {
+    switch (count) {
+      case 0:
+        return BigInt(0);
+
+      case 1:
+        return BigInt(((value[0] ^ 0x0000_00ff) * -1) - 1);
+
+      case 2:
+        return BigInt((((value[0] + (value[1] << 8)) ^ 0x0000_ffff) * -1) - 1);
+
+      case 4:
+        return BigInt((((value[0] + (value[1] << 8) + (value[2] << 16) + (value[3] * 0x1_00_00_00)) ^ 0xffff_ffff) * -1) - 1);
+    }
+
+    const dvI = new DataView(value.buffer, value.byteOffset);
+
+    if (count === 8) {
+      return dvI.getBigInt64(0, true);
+    }
+
+    let result = BigInt(0);
+    const mod = count % 2;
+
+    for (let i = count - 2; i >= mod; i -= 2) {
+      result = (result * U16_MAX) + BigInt(dvI.getUint16(i, true) ^ 0xffff);
+    }
+
+    if (mod) {
+      result = (result * U8_MAX) + BigInt(value[0] ^ 0xff);
+    }
+
+    return (result * -_1n) - _1n;
+  }
+
+  switch (count) {
+    case 0:
+      return BigInt(0);
+
+    case 1:
+      return BigInt(value[0]);
+
+    case 2:
+      return BigInt(value[0] + (value[1] << 8));
+
+    case 4:
+      return BigInt(value[0] + (value[1] << 8) + (value[2] << 16) + (value[3] * 0x1_00_00_00));
+  }
+
+  const dvI = new DataView(value.buffer, value.byteOffset);
+
+  switch (count) {
+    case 8:
+      return dvI.getBigUint64(0, true);
+
+    case 16:
+      return (dvI.getBigUint64(8, true) * U64_MAX) + dvI.getBigUint64(0, true);
+
+    default: {
+      let result = BigInt(0);
+      const mod = count % 2;
+
+      for (let i = count - 2; i >= mod; i -= 2) {
+        result = (result * U16_MAX) + BigInt(dvI.getUint16(i, true));
+      }
+
+      if (mod) {
+        result = (result * U8_MAX) + BigInt(value[0]);
+      }
+
+      return result;
+    }
+  }
+}