@lodestar/utils 1.35.0-dev.e18102ed8c → 1.35.0-dev.f45a2be721

package/src/retry.ts

@@ -0,0 +1,75 @@
+import {ErrorAborted} from "./errors.js";
+import {sleep} from "./sleep.js";
+
+export type RetryOptions = {
+  /**
+   * The maximum amount of times to retry the operation. Default is 5
+   */
+  retries?: number;
+  /**
+   * An optional Function that is invoked after the provided callback throws.
+   * It expects a boolean to know if it should retry or not.
+   * Useful to make retrying conditional on the type of error thrown.
+   */
+  shouldRetry?: (lastError: Error) => boolean;
+  /**
+   * An optional Function that is invoked right before a retry is performed.
+   * It's passed the Error that triggered it and a number identifying the attempt.
+   * Useful to track number of retries and errors in logs or metrics.
+   */
+  onRetry?: (lastError: Error, attempt: number) => unknown;
+  /**
+   * Milliseconds to wait before retrying again
+   */
+  retryDelay?: number;
+  /**
+   * Abort signal to stop retrying
+   */
+  signal?: AbortSignal;
+};
+
+/**
+ * Retry a given function on error.
+ * @param fn Async callback to retry. Invoked with 1 parameter
+ * A Number identifying the attempt. The absolute first attempt (before any retries) is 1
+ * @param opts
+ */
+export async function retry<A>(fn: (attempt: number) => A | Promise<A>, opts?: RetryOptions): Promise<A> {
+  const maxRetries = opts?.retries ?? 5;
+  // Number of retries + the initial attempt
+  const maxAttempts = maxRetries + 1;
+  const shouldRetry = opts?.shouldRetry;
+  const onRetry = opts?.onRetry;
+
+  let lastError: Error = Error("RetryError");
+  for (let i = 1; i <= maxAttempts; i++) {
+    // If not the first attempt
+    if (i > 1) {
+      if (opts?.signal?.aborted) {
+        throw new ErrorAborted("retry");
+      }
+      // Invoke right before retrying
+      onRetry?.(lastError, i);
+    }
+
+    try {
+      return await fn(i);
+    } catch (e) {
+      lastError = e as Error;
+
+      if (i === maxAttempts) {
+        // Reached maximum number of attempts, there's no need to check if we should retry
+        break;
+      }
+
+      if (shouldRetry && !shouldRetry(lastError)) {
+        break;
+      }
+
+      if (opts?.retryDelay !== undefined) {
+        await sleep(opts?.retryDelay, opts?.signal);
+      }
+    }
+  }
+  throw lastError;
+}

package/src/sleep.ts

@@ -0,0 +1,32 @@
+import {ErrorAborted} from "./errors.js";
+
+/**
+ * Abortable sleep function. Cleans everything on all cases preventing leaks
+ * On abort throws ErrorAborted
+ */
+export async function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  if (ms < 0) {
+    return;
+  }
+
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(new ErrorAborted());
+
+    let onDone: () => void = () => {};
+
+    const timeout = setTimeout(() => {
+      onDone();
+      resolve();
+    }, ms);
+    const onAbort = (): void => {
+      onDone();
+      reject(new ErrorAborted());
+    };
+    if (signal) signal.addEventListener("abort", onAbort);
+
+    onDone = () => {
+      clearTimeout(timeout);
+      if (signal) signal.removeEventListener("abort", onAbort);
+    };
+  });
+}

package/src/sort.ts

@@ -0,0 +1,9 @@
+export function isSorted(indices: number[]): boolean {
+  for (let i = 0, prevIndex = -1; i < indices.length; i++) {
+    if (indices[i] <= prevIndex) {
+      return false;
+    }
+    prevIndex = indices[i];
+  }
+  return true;
+}

package/src/timeout.ts

@@ -0,0 +1,27 @@
+import {anySignal} from "any-signal";
+import {ErrorAborted, TimeoutError} from "./errors.js";
+import {sleep} from "./sleep.js";
+
+export async function withTimeout<T>(
+  asyncFn: (timeoutAndParentSignal?: AbortSignal) => Promise<T>,
+  timeoutMs: number,
+  signal?: AbortSignal
+): Promise<T> {
+  if (signal?.aborted) {
+    throw new ErrorAborted();
+  }
+
+  const timeoutAbortController = new AbortController();
+  const timeoutAndParentSignal = anySignal([timeoutAbortController.signal, ...(signal ? [signal] : [])]);
+
+  async function timeoutPromise(signal: AbortSignal): Promise<never> {
+    await sleep(timeoutMs, signal);
+    throw new TimeoutError();
+  }
+
+  try {
+    return await Promise.race([asyncFn(timeoutAndParentSignal), timeoutPromise(timeoutAndParentSignal)]);
+  } finally {
+    timeoutAbortController.abort();
+  }
+}

package/src/types.ts

@@ -0,0 +1,48 @@
+/**
+ * Recursively make all properties optional
+ */
+type Primitive = string | number | boolean | bigint | symbol | null | undefined;
+type Builtin = Primitive | Date | Error | RegExp;
+
+export type RecursivePartial<T> =
+  // stop on built-ins (incl. Error) and functions
+  T extends Builtin
+    ? T
+    : // arrays and readonly arrays
+      T extends ReadonlyArray<infer U>
+      ? ReadonlyArray<RecursivePartial<U>>
+      : T extends Array<infer U>
+        ? Array<RecursivePartial<U>>
+        : // (optionally: Map/Set support)
+          T extends Map<infer K, infer V>
+          ? Map<RecursivePartial<K>, RecursivePartial<V>>
+          : T extends Set<infer U>
+            ? Set<RecursivePartial<U>>
+            : // plain objects
+              T extends object
+              ? {[P in keyof T]?: RecursivePartial<T[P]>}
+              : // fallback (shouldn’t be hit often)
+                T;
+
+/** Type safe wrapper for Number constructor that takes 'any' */
+export function bnToNum(bn: bigint): number {
+  return Number(bn);
+}
+
+export type NonEmptyArray<T> = [T, ...T[]];
+
+/**
+ * ArrayToTuple converts an `Array<T>` to `[T, ...T]`
+ *
+ * eg: `[1, 2, 3]` from type `number[]` to `[number, number, number]`
+ */
+export type ArrayToTuple<Tuple extends NonEmptyArray<unknown>> = {
+  [Index in keyof Tuple]: Tuple[Index];
+};
+
+/**
+ * Convert optional attributes of an object to required
+ */
+export type RequiredSelective<T, Keys extends keyof T> = T & {
+  [K in Keys]-?: T[K];
+};

package/src/url.ts

@@ -0,0 +1,29 @@
+export function isValidHttpUrl(urlStr: string): boolean {
+  let url: URL;
+  try {
+    url = new URL(urlStr);
+
+    // `new URL` encodes the username/password with the userinfo percent-encode set.
+    // This means the `%` character is not encoded, but others are (such as `=`).
+    // If a username/password contain a `%`, they will not be able to be decoded.
+    //
+    // Make sure that we can successfully decode the username and password here.
+    //
+    // Unfortunately this means we don't accept every character supported by RFC-3986.
+    decodeURIComponent(url.username);
+    decodeURIComponent(url.password);
+  } catch (_) {
+    return false;
+  }
+
+  return url.protocol === "http:" || url.protocol === "https:";
+}
+
+/**
+ * Sanitize URL to prevent leaking user credentials in logs or metrics
+ *
+ * Note: `urlStr` must be a valid URL
+ */
+export function toPrintableUrl(urlStr: string): string {
+  return new URL(urlStr).origin;
+}

package/src/verifyMerkleBranch.ts

@@ -0,0 +1,27 @@
+import {digest, digest64} from "@chainsafe/as-sha256";
+
+export function hash(...inputs: Uint8Array[]): Uint8Array {
+  return digest(Buffer.concat(inputs));
+}
+
+/**
+ * Verify that the given ``leaf`` is on the merkle branch ``proof``
+ * starting with the given ``root``.
+ */
+export function verifyMerkleBranch(
+  leaf: Uint8Array,
+  proof: Uint8Array[],
+  depth: number,
+  index: number,
+  root: Uint8Array
+): boolean {
+  let value = leaf;
+  for (let i = 0; i < depth; i++) {
+    if (Math.floor(index / 2 ** i) % 2) {
+      value = digest64(Buffer.concat([proof[i], value]));
+    } else {
+      value = digest64(Buffer.concat([value, proof[i]]));
+    }
+  }
+  return Buffer.from(value.buffer, value.byteOffset, value.byteLength).equals(root);
+}

package/src/waitFor.ts

@@ -0,0 +1,87 @@
+import {ErrorAborted, TimeoutError} from "./errors.js";
+
+export type WaitForOpts = {
+  /** Time in milliseconds between checking condition */
+  interval?: number;
+  /** Time in milliseconds to wait before throwing TimeoutError */
+  timeout?: number;
+  /** Abort signal to stop waiting for condition by throwing ErrorAborted */
+  signal?: AbortSignal;
+};
+
+/**
+ * Wait for a condition to be true
+ */
+export function waitFor(condition: () => boolean, opts: WaitForOpts = {}): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const {interval = 10, timeout = Infinity, signal} = opts;
+
+    if (signal?.aborted) {
+      return reject(new ErrorAborted());
+    }
+
+    if (condition()) {
+      return resolve();
+    }
+
+    let onDone: () => void = () => {};
+
+    const timeoutId = setTimeout(() => {
+      onDone();
+      reject(new TimeoutError());
+    }, timeout);
+
+    const intervalId = setInterval(() => {
+      if (condition()) {
+        onDone();
+        resolve();
+      }
+    }, interval);
+
+    const onAbort = (): void => {
+      onDone();
+      reject(new ErrorAborted());
+    };
+    if (signal) signal.addEventListener("abort", onAbort);
+
+    onDone = () => {
+      clearTimeout(timeoutId);
+      clearInterval(intervalId);
+      if (signal) signal.removeEventListener("abort", onAbort);
+    };
+  });
+}
+
+export interface ElapsedTimeTracker {
+  (): boolean;
+  msSinceLastCall: number;
+}
+
+/**
+ * Create a tracker which keeps track of the last time a function was called
+ *
+ * @param durationMs
+ * @returns
+ */
+export function createElapsedTimeTracker({minElapsedTime}: {minElapsedTime: number}): ElapsedTimeTracker {
+  // Initialized with undefined as the function has not been called yet
+  let lastTimeCalled: number | undefined = undefined;
+
+  function elapsedTimeTracker(): boolean {
+    const now = Date.now();
+    const msSinceLastCall = now - (lastTimeCalled ?? 0);
+
+    if (msSinceLastCall > minElapsedTime) {
+      // Do not reset timer if called before timer elapsed
+      lastTimeCalled = now;
+      return true;
+    }
+    return false;
+  }
+
+  return Object.assign(elapsedTimeTracker, {
+    get msSinceLastCall() {
+      return Date.now() - (lastTimeCalled ?? 0);
+    },
+  });
+}

package/src/yaml/index.ts

@@ -0,0 +1,12 @@
+import yaml from "js-yaml";
+import {schema} from "./schema.js";
+
+const {load, dump} = yaml;
+
+export function loadYaml<T = Record<string, unknown>>(yaml: string): T {
+  return load(yaml, {schema}) as T;
+}
+
+export function dumpYaml(yaml: unknown): string {
+  return dump(yaml, {schema});
+}

package/src/yaml/int.ts

@@ -0,0 +1,190 @@
+// Forked from https://github.com/nodeca/js-yaml/blob/master/lib/type/int.js
+// Currently only supports loading ints
+import yaml from "js-yaml";
+
+const {Type} = yaml;
+
+function isHexCode(c: number): boolean {
+  return (
+    // 0, 9
+    (0x30 <= c && c <= 0x39) ||
+    // A, F
+    (0x41 <= c && c <= 0x46) ||
+    // a, f
+    (0x61 <= c && c <= 0x66)
+  );
+}
+
+function isOctCode(c: number): boolean {
+  return 0x30 /* 0 */ <= c && c <= 0x37 /* 7 */;
+}
+
+function isDecCode(c: number): boolean {
+  return 0x30 /* 0 */ <= c && c <= 0x39 /* 9 */;
+}
+
+function resolveYamlInteger(data: string): boolean {
+  if (data === null) return false;
+
+  const max = data.length;
+  let ch: string,
+    index = 0,
+    hasDigits = false;
+
+  if (!max) return false;
+
+  ch = data[index];
+
+  // sign
+  if (ch === "-" || ch === "+") {
+    ch = data[++index];
+  }
+
+  if (ch === "0") {
+    // 0
+    if (index + 1 === max) return true;
+    ch = data[++index];
+
+    // base 2, base 8, base 16
+
+    if (ch === "b") {
+      // base 2
+      index++;
+
+      for (; index < max; index++) {
+        ch = data[index];
+        if (ch === "_") continue;
+        if (ch !== "0" && ch !== "1") return false;
+        hasDigits = true;
+      }
+      return hasDigits && ch !== "_";
+    }
+
+    if (ch === "x") {
+      // base 16
+      index++;
+
+      for (; index < max; index++) {
+        ch = data[index];
+        if (ch === "_") continue;
+        if (!isHexCode(data.charCodeAt(index))) return false;
+        hasDigits = true;
+      }
+      return hasDigits && ch !== "_";
+    }
+
+    // base 8
+    for (; index < max; index++) {
+      ch = data[index];
+      if (ch === "_") continue;
+      if (!isOctCode(data.charCodeAt(index))) return false;
+      hasDigits = true;
+    }
+    return hasDigits && ch !== "_";
+  }
+
+  // base 10 (except 0) or base 60
+
+  // value should not start with `_`;
+  if (ch === "_") return false;
+
+  for (; index < max; index++) {
+    ch = data[index];
+    if (ch === "_") continue;
+    if (ch === ":") break;
+    if (!isDecCode(data.charCodeAt(index))) {
+      return false;
+    }
+    hasDigits = true;
+  }
+
+  // Should have digits and should not end with `_`
+  if (!hasDigits || ch === "_") return false;
+
+  // if !base60 - done;
+  if (ch !== ":") return true;
+
+  // base60 almost not used, no needs to optimize
+  return /^(:[0-5]?[0-9])+$/.test(data.slice(index));
+}
+
+function constructYamlInteger(data: string): bigint {
+  let value: string | bigint = data,
+    sign = 1,
+    ch: string,
+    base: number | bigint;
+  const digits: number[] = [];
+
+  if (value.indexOf("_") !== -1) {
+    value = value.replace(/_/g, "");
+  }
+
+  ch = value[0];
+
+  if (ch === "-" || ch === "+") {
+    if (ch === "-") sign = -1;
+    value = value.slice(1);
+    ch = value[0];
+  }
+
+  if (value === "0") return BigInt(0);
+
+  if (ch === "0") {
+    if (value[1] === "b" || value[1] === "x") return BigInt(value) * BigInt(sign);
+    return BigInt("0o" + value) * BigInt(sign);
+  }
+
+  if (value.indexOf(":") !== -1) {
+    for (const v of value.split(":")) {
+      digits.unshift(parseInt(v, 10));
+    }
+    value = BigInt(0);
+    base = BigInt(1);
+
+    for (const d of digits) {
+      value = (BigInt(value) + BigInt(base)) * BigInt(d);
+      base = BigInt(base) * BigInt(60);
+    }
+
+    return value * BigInt(sign);
+  }
+
+  return BigInt(value) * BigInt(sign);
+}
+
+function isInteger(object: unknown): boolean {
+  return typeof object === "bigint" || typeof object === "number";
+}
+
+export const intType = new Type("tag:yaml.org,2002:int", {
+  kind: "scalar",
+  resolve: resolveYamlInteger,
+  construct: constructYamlInteger,
+  predicate: isInteger,
+  instanceOf: BigInt,
+  represent: {
+    // @ts-expect-error
+    binary: function binary(obj: number) {
+      return obj >= 0 ? "0b" + obj.toString(2) : "-0b" + obj.toString(2).slice(1);
+    },
+    // @ts-expect-error
+    octal: function octal(obj: number) {
+      return obj >= 0 ? "0" + obj.toString(8) : "-0" + obj.toString(8).slice(1);
+    },
+    // @ts-expect-error
+    decimal: function decimal(obj: number) {
+      return obj.toString(10);
+    },
+    // @ts-expect-error
+    hexadecimal: function hexadecimal(obj: number) {
+      return obj >= 0 ? "0x" + obj.toString(16).toUpperCase() : "-0x" + obj.toString(16).toUpperCase().slice(1);
+    },
+  },
+  defaultStyle: "decimal",
+  styleAliases: {
+    binary: [2, "bin"],
+    octal: [8, "oct"],
+    decimal: [10, "dec"],
+    hexadecimal: [16, "hex"],
+  },
+});

package/src/yaml/schema.ts

@@ -0,0 +1,8 @@
+import yml, {FAILSAFE_SCHEMA, Type} from "js-yaml";
+import {intType} from "./int.js";
+
+export const schema = FAILSAFE_SCHEMA.extend({
+  // @ts-expect-error
+  implicit: [yml.types.null as Type, yml.types.bool as Type, intType, yml.types.float as Type],
+  explicit: [],
+});