@lodestar/utils 1.35.0-dev.f80d2d52da → 1.35.0-dev.fcf8d024ea

package/src/bytes/browser.ts

@@ -0,0 +1,123 @@
+// "0".charCodeAt(0) = 48
+const CHAR_CODE_0 = 48;
+// "x".charCodeAt(0) = 120
+const CHAR_CODE_X = 120;
+
+export function toHex(bytes: Uint8Array): string {
+  const charCodes = new Array<number>(bytes.length * 2 + 2);
+  charCodes[0] = CHAR_CODE_0;
+  charCodes[1] = CHAR_CODE_X;
+
+  bytesIntoCharCodes(bytes, charCodes);
+  return String.fromCharCode(...charCodes);
+}
+
+const rootCharCodes = new Array<number>(32 * 2 + 2);
+rootCharCodes[0] = CHAR_CODE_0;
+rootCharCodes[1] = CHAR_CODE_X;
+
+/**
+ * Convert a Uint8Array, length 32, to 0x-prefixed hex string
+ */
+export function toRootHex(root: Uint8Array): string {
+  if (root.length !== 32) {
+    throw Error(`Expect root to be 32 bytes, got ${root.length}`);
+  }
+
+  bytesIntoCharCodes(root, rootCharCodes);
+  return String.fromCharCode(...rootCharCodes);
+}
+
+const pubkeyCharCodes = new Array<number>(48 * 2 + 2);
+pubkeyCharCodes[0] = CHAR_CODE_0;
+pubkeyCharCodes[1] = CHAR_CODE_X;
+
+/**
+ * Convert a Uint8Array, length 48, to 0x-prefixed hex string
+ */
+export function toPubkeyHex(pubkey: Uint8Array): string {
+  if (pubkey.length !== CHAR_CODE_0) {
+    throw Error(`Expect pubkey to be 48 bytes, got ${pubkey.length}`);
+  }
+
+  bytesIntoCharCodes(pubkey, pubkeyCharCodes);
+  return String.fromCharCode(...pubkeyCharCodes);
+}
+
+export function fromHex(hex: string): Uint8Array {
+  if (typeof hex !== "string") {
+    throw new Error(`hex argument type ${typeof hex} must be of type string`);
+  }
+
+  if (hex.startsWith("0x")) {
+    hex = hex.slice(2);
+  }
+
+  if (hex.length % 2 !== 0) {
+    throw new Error(`hex string length ${hex.length} must be multiple of 2`);
+  }
+
+  const byteLen = hex.length / 2;
+  const bytes = new Uint8Array(byteLen);
+  for (let i = 0; i < byteLen; i++) {
+    const byte2i = charCodeToByte(hex.charCodeAt(i * 2));
+    const byte2i1 = charCodeToByte(hex.charCodeAt(i * 2 + 1));
+    bytes[i] = (byte2i << 4) | byte2i1;
+  }
+  return bytes;
+}
+
+export function fromHexInto(hex: string, buffer: Uint8Array): void {
+  if (hex.startsWith("0x")) {
+    hex = hex.slice(2);
+  }
+
+  if (hex.length !== buffer.length * 2) {
+    throw new Error(`hex string length ${hex.length} must be exactly double the buffer length ${buffer.length}`);
+  }
+
+  for (let i = 0; i < buffer.length; i++) {
+    const byte2i = charCodeToByte(hex.charCodeAt(i * 2));
+    const byte2i1 = charCodeToByte(hex.charCodeAt(i * 2 + 1));
+    buffer[i] = (byte2i << 4) | byte2i1;
+  }
+}
+
+/**
+ * Populate charCodes from bytes. Note that charCodes index 0 and 1 ("0x") are not populated.
+ */
+function bytesIntoCharCodes(bytes: Uint8Array, charCodes: number[]): void {
+  if (bytes.length * 2 + 2 !== charCodes.length) {
+    throw Error(`Expect charCodes to be of length ${bytes.length * 2 + 2}, got ${charCodes.length}`);
+  }
+
+  for (let i = 0; i < bytes.length; i++) {
+    const byte = bytes[i];
+    const first = (byte & 0xf0) >> 4;
+    const second = byte & 0x0f;
+
+    // "0".charCodeAt(0) = 48
+    // "a".charCodeAt(0) = 97 => delta = 87
+    charCodes[2 + 2 * i] = first < 10 ? first + 48 : first + 87;
+    charCodes[2 + 2 * i + 1] = second < 10 ? second + 48 : second + 87;
+  }
+}
+
+function charCodeToByte(charCode: number): number {
+  // "a".charCodeAt(0) = 97, "f".charCodeAt(0) = 102 => delta = 87
+  if (charCode >= 97 && charCode <= 102) {
+    return charCode - 87;
+  }
+
+  // "A".charCodeAt(0) = 65, "F".charCodeAt(0) = 70 => delta = 55
+  if (charCode >= 65 && charCode <= 70) {
+    return charCode - 55;
+  }
+
+  // "0".charCodeAt(0) = 48, "9".charCodeAt(0) = 57 => delta = 48
+  if (charCode >= 48 && charCode <= 57) {
+    return charCode - 48;
+  }
+
+  throw new Error(`Invalid hex character code: ${charCode}`);
+}

package/src/bytes/index.ts

@@ -0,0 +1,29 @@
+import {
+  fromHex as browserFromHex,
+  fromHexInto as browserFromHexInto,
+  toHex as browserToHex,
+  toPubkeyHex as browserToPubkeyHex,
+  toRootHex as browserToRootHex,
+} from "./browser.js";
+import {
+  fromHex as nodeFromHex,
+  toHex as nodeToHex,
+  toPubkeyHex as nodeToPubkeyHex,
+  toRootHex as nodeToRootHex,
+} from "./nodejs.js";
+
+let toHex = browserToHex;
+let toRootHex = browserToRootHex;
+let toPubkeyHex = browserToPubkeyHex;
+let fromHex = browserFromHex;
+// there is no fromHexInto for NodeJs as the performance of browserFromHexInto is >100x faster
+const fromHexInto = browserFromHexInto;
+
+if (typeof Buffer !== "undefined") {
+  toHex = nodeToHex;
+  toRootHex = nodeToRootHex;
+  toPubkeyHex = nodeToPubkeyHex;
+  fromHex = nodeFromHex;
+}
+
+export {toHex, toRootHex, toPubkeyHex, fromHex, fromHexInto};

package/src/bytes/nodejs.ts

@@ -0,0 +1,63 @@
+export function toHex(buffer: Uint8Array | Parameters<typeof Buffer.from>[0]): string {
+  if (Buffer.isBuffer(buffer)) {
+    return "0x" + buffer.toString("hex");
+  }
+  if (buffer instanceof Uint8Array) {
+    return "0x" + Buffer.from(buffer.buffer, buffer.byteOffset, buffer.length).toString("hex");
+  }
+  return "0x" + Buffer.from(buffer).toString("hex");
+}
+
+// Shared buffer to convert root to hex
+let rootBuf: Buffer | undefined;
+
+/**
+ * Convert a Uint8Array, length 32, to 0x-prefixed hex string
+ */
+export function toRootHex(root: Uint8Array): string {
+  if (root.length !== 32) {
+    throw Error(`Expect root to be 32 bytes, got ${root.length}`);
+  }
+
+  if (rootBuf === undefined) {
+    rootBuf = Buffer.alloc(32);
+  }
+
+  rootBuf.set(root);
+  return `0x${rootBuf.toString("hex")}`;
+}
+
+// Shared buffer to convert pubkey to hex
+let pubkeyBuf: Buffer | undefined;
+
+export function toPubkeyHex(pubkey: Uint8Array): string {
+  if (pubkey.length !== 48) {
+    throw Error(`Expect pubkey to be 48 bytes, got ${pubkey.length}`);
+  }
+
+  if (pubkeyBuf === undefined) {
+    pubkeyBuf = Buffer.alloc(48);
+  }
+
+  pubkeyBuf.set(pubkey);
+  return `0x${pubkeyBuf.toString("hex")}`;
+}
+
+export function fromHex(hex: string): Uint8Array {
+  if (typeof hex !== "string") {
+    throw new Error(`hex argument type ${typeof hex} must be of type string`);
+  }
+
+  if (hex.startsWith("0x")) {
+    hex = hex.slice(2);
+  }
+
+  if (hex.length % 2 !== 0) {
+    throw new Error(`hex string length ${hex.length} must be multiple of 2`);
+  }
+
+  const b = Buffer.from(hex, "hex");
+  return new Uint8Array(b.buffer, b.byteOffset, b.length);
+}
+
+/// the performance of fromHexInto using a preallocated buffer is very bad compared to browser so I moved it to the benchmark

package/src/bytes.ts

@@ -0,0 +1,84 @@
+import {toBigIntBE, toBigIntLE, toBufferBE, toBufferLE} from "bigint-buffer";
+
+type Endianness = "le" | "be";
+
+const hexByByte: string[] = [];
+/**
+ * @deprecated Use toHex() instead.
+ */
+export function toHexString(bytes: Uint8Array): string {
+  let hex = "0x";
+  for (const byte of bytes) {
+    if (!hexByByte[byte]) {
+      hexByByte[byte] = byte < 16 ? "0" + byte.toString(16) : byte.toString(16);
+    }
+    hex += hexByByte[byte];
+  }
+  return hex;
+}
+
+/**
+ * Return a byte array from a number or BigInt
+ */
+export function intToBytes(value: bigint | number, length: number, endianness: Endianness = "le"): Buffer {
+  return bigIntToBytes(BigInt(value), length, endianness);
+}
+
+/**
+ * Convert byte array in LE to integer.
+ */
+export function bytesToInt(value: Uint8Array, endianness: Endianness = "le"): number {
+  return Number(bytesToBigInt(value, endianness));
+}
+
+export function bigIntToBytes(value: bigint, length: number, endianness: Endianness = "le"): Buffer {
+  if (endianness === "le") {
+    return toBufferLE(value, length);
+  }
+  if (endianness === "be") {
+    return toBufferBE(value, length);
+  }
+  throw new Error("endianness must be either 'le' or 'be'");
+}
+
+export function bytesToBigInt(value: Uint8Array, endianness: Endianness = "le"): bigint {
+  if (!(value instanceof Uint8Array)) {
+    throw new TypeError("expected a Uint8Array");
+  }
+
+  if (endianness === "le") {
+    return toBigIntLE(value as Buffer);
+  }
+  if (endianness === "be") {
+    return toBigIntBE(value as Buffer);
+  }
+  throw new Error("endianness must be either 'le' or 'be'");
+}
+
+export function formatBytes(bytes: number): string {
+  if (bytes < 0) {
+    throw new Error("bytes must be a positive number, got " + bytes);
+  }
+
+  if (bytes === 0) {
+    return "0 Bytes";
+  }
+
+  // size of a kb
+  const k = 1024;
+
+  // only support up to GB
+  const units = ["Bytes", "KB", "MB", "GB"];
+  const i = Math.min(Math.floor(Math.log(bytes) / Math.log(k)), units.length - 1);
+  const formattedSize = (bytes / Math.pow(k, i)).toFixed(2);
+
+  return `${formattedSize} ${units[i]}`;
+}
+
+export function xor(a: Uint8Array, b: Uint8Array): Uint8Array {
+  const length = Math.min(a.length, b.length);
+  for (let i = 0; i < length; i++) {
+    a[i] = a[i] ^ b[i];
+  }
+  return a;
+}

package/src/command.ts

@@ -0,0 +1,74 @@
+import type {Argv, Options} from "yargs";
+
+export interface CliExample {
+  command: string;
+  title?: string;
+  description?: string;
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: We need to use `any` type here
+export interface CliOptionDefinition<T = any> extends Options {
+  example?: Omit<CliExample, "title">;
+  // Ensure `type` property matches type of `T`
+  type: T extends string
+    ? "string"
+    : T extends number
+      ? "number"
+      : T extends boolean
+        ? "boolean"
+        : T extends Array<unknown>
+          ? "array"
+          : never;
+}
+
+export type CliCommandOptions<OwnArgs> = Required<{
+  [K in keyof OwnArgs]: undefined extends OwnArgs[K]
+    ? CliOptionDefinition<OwnArgs[K]>
+    : // If arg cannot be undefined it must specify a default value or be provided by the user
+      CliOptionDefinition<OwnArgs[K]> & (Required<Pick<Options, "default">> | {demandOption: true});
+}>;
+
+// biome-ignore lint/suspicious/noExplicitAny: We need to use `any` type here
+export interface CliCommand<OwnArgs = Record<never, never>, ParentArgs = Record<never, never>, R = any> {
+  command: string;
+  describe: string;
+  /**
+   * The folder in docs/pages that the cli.md should be placed in.  If not provided no
+   * cli flags page will be generated for the command
+   */
+  docsFolder?: string;
+  examples?: CliExample[];
+  options?: CliCommandOptions<OwnArgs>;
+  // 1st arg: any = free own sub command options
+  // 2nd arg: subcommand parent options is = to this command options + parent options
+  // biome-ignore lint/suspicious/noExplicitAny: We need to use `any` type here
+  subcommands?: CliCommand<any, OwnArgs & ParentArgs>[];
+  handler?: (args: OwnArgs & ParentArgs) => Promise<R>;
+}
+
+/**
+ * Register a CliCommand type to yargs. Recursively registers subcommands too.
+ * @param yargs
+ * @param cliCommand
+ */
+
+// biome-ignore lint/suspicious/noExplicitAny: We need to use `any` type here
+export function registerCommandToYargs(yargs: Argv, cliCommand: CliCommand<any, any>): void {
+  yargs.command({
+    command: cliCommand.command,
+    describe: cliCommand.describe,
+    builder: (yargsBuilder) => {
+      yargsBuilder.options(cliCommand.options ?? {});
+      for (const subcommand of cliCommand.subcommands ?? []) {
+        registerCommandToYargs(yargsBuilder, subcommand);
+      }
+      if (cliCommand.examples) {
+        for (const example of cliCommand.examples) {
+          yargsBuilder.example(`$0 ${example.command}`, example.description ?? "");
+        }
+      }
+      return yargs;
+    },
+    handler: cliCommand.handler ?? function emptyHandler(): void {},
+  });
+}

package/src/diff.ts

@@ -0,0 +1,234 @@
+import fs from "node:fs";
+
+const primitiveTypeof = ["number", "string", "bigint", "boolean"];
+export type BufferType = Uint8Array | Uint32Array;
+export type PrimitiveType = number | string | bigint | boolean | BufferType;
+export type DiffableCollection = Record<string | number, PrimitiveType>;
+export type Diffable = PrimitiveType | Array<PrimitiveType> | DiffableCollection;
+
+export interface Diff {
+  objectPath: string;
+  errorMessage?: string;
+  val1: Diffable;
+  val2: Diffable;
+}
+
+export function diffUint8Array(val1: Uint8Array, val2: PrimitiveType, objectPath: string): Diff[] {
+  if (!(val2 instanceof Uint8Array)) {
+    return [
+      {
+        objectPath,
+        errorMessage: `val1${objectPath} is a Uint8Array, but val2${objectPath} is not`,
+        val1,
+        val2,
+      },
+    ];
+  }
+  const hex1 = Buffer.from(val1).toString("hex");
+  const hex2 = Buffer.from(val2).toString("hex");
+  if (hex1 !== hex2) {
+    return [
+      {
+        objectPath,
+        val1: `0x${hex1}`,
+        val2: `0x${hex2}`,
+      },
+    ];
+  }
+  return [];
+}
+
+export function diffUint32Array(val1: Uint32Array, val2: PrimitiveType, objectPath: string): Diff[] {
+  if (!(val2 instanceof Uint32Array)) {
+    return [
+      {
+        objectPath,
+        errorMessage: `val1${objectPath} is a Uint32Array, but val2${objectPath} is not`,
+        val1,
+        val2,
+      },
+    ];
+  }
+  const diffs: Diff[] = [];
+  val1.forEach((value, index) => {
+    const value2 = val2[index];
+    if (value !== value2) {
+      diffs.push({
+        objectPath: `${objectPath}[${index}]`,
+        val1: `0x${value.toString(16).padStart(8, "0")}`,
+        val2: value2 ? `0x${val2[index].toString(16).padStart(8, "0")}` : "undefined",
+      });
+    }
+  });
+  return diffs;
+}
+
+function diffPrimitiveValue(val1: PrimitiveType, val2: PrimitiveType, objectPath: string): Diff[] {
+  if (val1 instanceof Uint8Array) {
+    return diffUint8Array(val1, val2, objectPath);
+  }
+  if (val1 instanceof Uint32Array) {
+    return diffUint32Array(val1, val2, objectPath);
+  }
+
+  const diff = {objectPath, val1, val2} as Diff;
+  const type1 = typeof val1;
+  if (!primitiveTypeof.includes(type1)) {
+    diff.errorMessage = `val1${objectPath} is not a supported type`;
+  }
+  const type2 = typeof val2;
+  if (!primitiveTypeof.includes(type2)) {
+    diff.errorMessage = `val2${objectPath} is not a supported type`;
+  }
+  if (type1 !== type2) {
+    diff.errorMessage = `val1${objectPath} is not the same type as val2${objectPath}`;
+  }
+  if (val1 !== val2) {
+    return [diff];
+  }
+  return [];
+}
+
+function isPrimitiveValue(val: unknown): val is PrimitiveType {
+  if (Array.isArray(val)) return false;
+  if (typeof val === "object") {
+    return val instanceof Uint8Array || val instanceof Uint32Array;
+  }
+  return true;
+}
+
+function isDiffable(val: unknown): val is Diffable {
+  return !(typeof val === "function" || typeof val === "symbol" || typeof val === "undefined" || val === null);
+}
+
+export function getDiffs(val1: Diffable, val2: Diffable, objectPath: string): Diff[] {
+  if (isPrimitiveValue(val1)) {
+    if (!isPrimitiveValue(val2)) {
+      return [
+        {
+          objectPath,
+          errorMessage: `val1${objectPath} is a primitive value and val2${objectPath} is not`,
+          val1,
+          val2,
+        },
+      ];
+    }
+    return diffPrimitiveValue(val1, val2, objectPath);
+  }
+
+  const isArray = Array.isArray(val1);
+  let errorMessage: string | undefined;
+  if (isArray && !Array.isArray(val2)) {
+    errorMessage = `val1${objectPath} is an array and val2${objectPath} is not`;
+  } else if (typeof val1 === "object" && typeof val2 !== "object") {
+    errorMessage = `val1${objectPath} is a nested object and val2${objectPath} is not`;
+  }
+  if (errorMessage) {
+    return [
+      {
+        objectPath,
+        errorMessage,
+        val1,
+        val2,
+      },
+    ];
+  }
+
+  const diffs: Diff[] = [];
+  for (const [index, value] of Object.entries(val1)) {
+    if (!isDiffable(value)) {
+      diffs.push({objectPath, val1, val2, errorMessage: `val1${objectPath} is not Diffable`});
+      continue;
+    }
+    const value2 = (val2 as DiffableCollection)[index];
+    if (!isDiffable(value2)) {
+      diffs.push({objectPath, val1, val2, errorMessage: `val2${objectPath} is not Diffable`});
+      continue;
+    }
+    const innerPath = isArray ? `${objectPath}[${index}]` : `${objectPath}.${index}`;
+    diffs.push(...getDiffs(value, value2, innerPath));
+  }
+  return diffs;
+}
+
+/**
+ * Find the different values on complex, nested objects. Outputs the path through the object to
+ * each value that does not match from val1 and val2. Optionally can output the values that differ.
+ *
+ * For objects that differ greatly, can write to a file instead of the terminal for analysis
+ *
+ * ## Example
+ * ```ts
+ * const obj1 = {
+ *   key1: {
+ *     key2: [
+ *       { key3: 1 },
+ *       { key3: new Uint8Array([1, 2, 3]) }
+ *     ]
+ *   },
+ *   key4: new Uint32Array([1, 2, 3]),
+ *   key5: 362436
+ * };
+ *
+ * const obj2 = {
+ *   key1: {
+ *     key2: [
+ *       { key3: 1 },
+ *       { key3: new Uint8Array([1, 2, 4]) }
+ *     ]
+ *   },
+ *   key4: new Uint32Array([1, 2, 4])
+ *   key5: true
+ * };
+ *
+ * diffObjects(obj1, obj2, true);
+ *
+ *
+ * ```
+ *
+ * ## Output
+ * ```sh
+ * val.key1.key2[1].key3
+ *   - 0x010203
+ *   - 0x010204
+ * val.key4[2]
+ *   - 0x00000003
+ *   - 0x00000004
+ * val.key5
+ *   val1.key5 is not the same type as val2.key5
+ *   - 362436
+ *   - true
+ * ```
+ */
+export function diff(val1: unknown, val2: unknown, outputValues = false, filename?: string): void {
+  if (!isDiffable(val1)) {
+    // biome-ignore lint/suspicious/noConsole: We need to log to the console
+    console.log("val1 is not Diffable");
+    return;
+  }
+  if (!isDiffable(val2)) {
+    // biome-ignore lint/suspicious/noConsole: We need to log to the console
+    console.log("val2 is not Diffable");
+    return;
+  }
+  const diffs = getDiffs(val1, val2, "");
+  let output = "";
+  if (diffs.length) {
+    for (const diff of diffs) {
+      let diffOutput = `value${diff.objectPath}`;
+      if (diff.errorMessage) {
+        diffOutput += `\n  ${diff.errorMessage}`;
+      }
+      if (outputValues) {
+        diffOutput += `\n  - ${diff.val1.toString()}\n  - ${diff.val2.toString()}\n`;
+      }
+      output += `${diffOutput}\n`;
+    }
+    if (filename) {
+      fs.writeFileSync(filename, output);
+    } else {
+      // biome-ignore lint/suspicious/noConsole: We need to log to the console
+      console.log(output);
+    }
+  }
+}