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

package/src/math.ts

@@ -0,0 +1,55 @@
+/**
+ * Return the min number between two big numbers.
+ */
+export function bigIntMin(a: bigint, b: bigint): bigint {
+  return a < b ? a : b;
+}
+
+/**
+ * Return the max number between two big numbers.
+ */
+export function bigIntMax(a: bigint, b: bigint): bigint {
+  return a > b ? a : b;
+}
+
+export function intDiv(dividend: number, divisor: number): number {
+  return Math.floor(dividend / divisor);
+}
+
+/**
+ * Calculate the largest integer k such that k**2 <= n.
+ */
+export function intSqrt(n: number): number {
+  let x = n;
+  let y = intDiv(x + 1, 2);
+  while (y < x) {
+    x = y;
+    y = intDiv(x + intDiv(n, x), 2);
+  }
+  return x;
+}
+
+export function bigIntSqrt(n: bigint): bigint {
+  let x = n;
+  let y = (x + BigInt(1)) / BigInt(2);
+  while (y < x) {
+    x = y;
+    y = (x + n / x) / BigInt(2);
+  }
+  return x;
+}
+
+/**
+ * Regenerates a random integer between min (included) and max (excluded).
+ */
+export function randBetween(min: number, max: number): number {
+  return Math.floor(Math.random() * (max - min)) + min;
+}
+
+/**
+ * Wraps randBetween and returns a bigNumber.
+ * @returns {bigint}
+ */
+export function randBetweenBigInt(min: number, max: number): bigint {
+  return BigInt(randBetween(min, max));
+}

package/src/metrics.ts

@@ -0,0 +1,73 @@
+import {NonEmptyArray} from "./types.js";
+
+export type NoLabels = Record<string, never>;
+export type LabelsGeneric = Record<string, string | number>;
+export type LabelKeys<Labels extends LabelsGeneric> = Extract<keyof Labels, string>;
+export type CollectFn<Labels extends LabelsGeneric> = (metric: Gauge<Labels>) => void;
+
+export interface Gauge<Labels extends LabelsGeneric = NoLabels> {
+  inc: NoLabels extends Labels ? (value?: number) => void : (labels: Labels, value?: number) => void;
+  dec: NoLabels extends Labels ? (value?: number) => void : (labels: Labels, value?: number) => void;
+  set: NoLabels extends Labels ? (value: number) => void : (labels: Labels, value: number) => void;
+
+  collect?(): void;
+}
+
+export interface GaugeExtra<Labels extends LabelsGeneric = NoLabels> extends Omit<Gauge<Labels>, "collect"> {
+  addCollect(collectFn: CollectFn<Labels>): void;
+}
+
+export interface Histogram<Labels extends LabelsGeneric = NoLabels> {
+  startTimer(): NoLabels extends Labels ? () => number : (labels: Labels) => number;
+  startTimer<L extends Partial<Labels>>(
+    labels?: NoLabels extends Labels ? never : L
+  ): keyof Omit<Labels, keyof L> extends never ? () => number : (labels: Omit<Labels, keyof L>) => number;
+
+  observe: NoLabels extends Labels ? (value: number) => void : (labels: Labels, value: number) => void;
+
+  reset(): void;
+}
+
+export interface AvgMinMax<Labels extends LabelsGeneric = NoLabels> {
+  addGetValuesFn(getValuesFn: () => number[]): void;
+
+  set: NoLabels extends Labels ? (values: number[]) => void : (labels: Labels, values: number[]) => void;
+}
+
+export interface Counter<Labels extends LabelsGeneric = NoLabels> {
+  inc: NoLabels extends Labels ? (value?: number) => void : (labels: Labels, value?: number) => void;
+}
+
+export type GaugeConfig<Labels extends LabelsGeneric> = {
+  name: string;
+  help: string;
+} & (NoLabels extends Labels ? {labelNames?: never} : {labelNames: NonEmptyArray<LabelKeys<Labels>>});
+
+export type HistogramConfig<Labels extends LabelsGeneric> = GaugeConfig<Labels> & {
+  buckets: number[];
+};
+
+export type AvgMinMaxConfig<Labels extends LabelsGeneric> = GaugeConfig<Labels>;
+
+export type CounterConfig<Labels extends LabelsGeneric> = GaugeConfig<Labels>;
+
+export type StaticConfig<Labels extends LabelsGeneric> = {
+  name: GaugeConfig<Labels>["name"];
+  help: GaugeConfig<Labels>["help"];
+  value: Record<LabelKeys<Labels>, string>;
+};
+
+export interface MetricsRegister {
+  gauge<Labels extends LabelsGeneric = NoLabels>(config: GaugeConfig<Labels>): Gauge<Labels>;
+  histogram<Labels extends LabelsGeneric = NoLabels>(config: HistogramConfig<Labels>): Histogram<Labels>;
+  counter<Labels extends LabelsGeneric = NoLabels>(config: CounterConfig<Labels>): Counter<Labels>;
+}
+
+export interface MetricsRegisterExtra extends MetricsRegister {
+  gauge<Labels extends LabelsGeneric = NoLabels>(config: GaugeConfig<Labels>): GaugeExtra<Labels>;
+}
+
+export interface MetricsRegisterCustom extends MetricsRegisterExtra {
+  avgMinMax<Labels extends LabelsGeneric = NoLabels>(config: AvgMinMaxConfig<Labels>): AvgMinMax<Labels>;
+  static<Labels extends LabelsGeneric = NoLabels>(config: StaticConfig<Labels>): void;
+}

package/src/notNullish.ts

@@ -0,0 +1,11 @@
+/**
+ * Type-safe helper to filter out nullist values from an array
+ * ```js
+ * const array: (string | null)[] = ['foo', null];
+ * const filteredArray: string[] = array.filter(notEmpty);
+ * ```
+ * @param value
+ */
+export function notNullish<TValue>(value: TValue | null | undefined): value is TValue {
+  return value !== null && value !== undefined;
+}

package/src/objects.ts

@@ -0,0 +1,102 @@
+import Case from "case";
+
+export type KeyCase =
+  | "snake"
+  | "constant"
+  | "camel"
+  | "param"
+  | "header"
+  | "pascal" //Same as squish
+  | "dot"
+  | "notransform";
+
+export function toExpectedCase(
+  value: string,
+  expectedCase: KeyCase = "camel",
+  customCasingMap?: Record<string, string>
+): string {
+  if (expectedCase === "notransform") return value;
+  if (customCasingMap?.[value]) return customCasingMap[value];
+  switch (expectedCase) {
+    case "param":
+      return Case.kebab(value);
+    case "dot":
+      return Case.lower(value, ".", true);
+    default:
+      return Case[expectedCase](value);
+  }
+}
+
+function isObjectObject(val: unknown): val is object {
+  return val != null && typeof val === "object" && Array.isArray(val) === false;
+}
+
+export function isPlainObject(o: unknown): o is object {
+  if (isObjectObject(o) === false) return false;
+
+  // If has modified constructor
+  const ctor = (o as Record<string, unknown>).constructor;
+  if (typeof ctor !== "function") return false;
+
+  // If has modified prototype
+  const prot = ctor.prototype;
+  if (isObjectObject(prot) === false) return false;
+
+  // If constructor does not have an Object-specific method
+  if (Object.prototype.hasOwnProperty.call(prot, "isPrototypeOf") === false) {
+    return false;
+  }
+
+  // Most likely a plain Object
+  return true;
+}
+
+export function isEmptyObject(value: unknown): boolean {
+  return isObjectObject(value) && Object.keys(value).length === 0;
+}
+
+/**
+ * Creates an object with the same keys as object and values generated by running each own enumerable
+ * string keyed property of object thru iteratee.
+ *
+ * Inspired on lodash.mapValues, see https://lodash.com/docs/4.17.15#mapValues
+ */
+// biome-ignore lint/suspicious/noExplicitAny: We need to use `any` type here
+export function mapValues<T extends {[K: string]: any}, R>(
+  obj: T,
+  iteratee: (value: T[keyof T], key: keyof T) => R
+): {[K in keyof T]: R} {
+  const output = {} as {[K in keyof T]: R};
+  for (const [key, value] of Object.entries(obj)) {
+    output[key as keyof T] = iteratee(value, key);
+  }
+  return output;
+}
+
+export function objectToExpectedCase<T extends Record<string, unknown> | Record<string, unknown>[] | unknown[]>(
+  obj: T,
+  expectedCase: "snake" | "constant" | "camel" | "param" | "header" | "pascal" | "dot" | "notransform" = "camel"
+): T {
+  if (Array.isArray(obj)) {
+    const newArr: unknown[] = [];
+    for (let i = 0; i < obj.length; i++) {
+      newArr[i] = objectToExpectedCase(obj[i] as T, expectedCase);
+    }
+    return newArr as unknown as T;
+  }
+
+  if (Object(obj) === obj) {
+    const newObj: Record<string, unknown> = {};
+    for (const name of Object.getOwnPropertyNames(obj)) {
+      const newName = toExpectedCase(name, expectedCase);
+      if (newName !== name && Object.prototype.hasOwnProperty.call(obj, newName)) {
+        throw new Error(`object already has a ${newName} property`);
+      }
+
+      newObj[newName] = objectToExpectedCase(obj[name] as Record<string, unknown>, expectedCase);
+    }
+    return newObj as T;
+  }
+
+  return obj;
+}

package/src/promise.ts

@@ -0,0 +1,163 @@
+import {ErrorAborted, TimeoutError} from "./errors.js";
+import {sleep} from "./sleep.js";
+import {ArrayToTuple, NonEmptyArray} from "./types.js";
+
+/**
+ * While promise t is not finished, call function `fn` per `interval`
+ */
+export async function callFnWhenAwait<T>(
+  p: Promise<T>,
+  fn: () => void,
+  interval: number,
+  signal?: AbortSignal
+): Promise<T> {
+  let done = false;
+  const logFn = async (): Promise<void> => {
+    while (!done) {
+      await sleep(interval, signal);
+      if (!done) fn();
+    }
+  };
+
+  const t = await Promise.race([p, logFn()]).finally(() => {
+    done = true;
+  });
+
+  return t as T;
+}
+
+/**
+ * Create a deferred promise
+ */
+export function defer<T>() {
+  let resolve!: (v: T) => void;
+  let reject!: (e: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return {promise, resolve, reject};
+}
+
+export type PromiseResult<T> = {
+  promise: Promise<T>;
+} & (
+  | {
+      status: "pending";
+    }
+  | {
+      status: "fulfilled";
+      value: T;
+      durationMs: number;
+    }
+  | {
+      status: "rejected";
+      reason: Error;
+      durationMs: number;
+    }
+);
+export type PromiseFulfilledResult<T> = PromiseResult<T> & {status: "fulfilled"};
+export type PromiseRejectedResult<T> = PromiseResult<T> & {status: "rejected"};
+
+/**
+ * Wrap a promise to an object to track the status and value of the promise
+ */
+export function wrapPromise<T>(promise: PromiseLike<T>): PromiseResult<T> {
+  const startedAt = Date.now();
+
+  const result = {
+    promise: promise.then(
+      (value) => {
+        result.status = "fulfilled";
+        (result as PromiseFulfilledResult<T>).value = value;
+        (result as PromiseFulfilledResult<T>).durationMs = Date.now() - startedAt;
+        return value;
+      },
+      (reason: unknown) => {
+        result.status = "rejected";
+        (result as PromiseRejectedResult<T>).reason = reason as Error;
+        (result as PromiseRejectedResult<T>).durationMs = Date.now() - startedAt;
+        throw reason;
+      }
+    ),
+    status: "pending",
+  } as PromiseResult<T>;
+
+  return result;
+}
+
+type ReturnPromiseWithTuple<Tuple extends NonEmptyArray<PromiseLike<unknown>>> = {
+  [Index in keyof ArrayToTuple<Tuple>]: PromiseResult<Awaited<Tuple[Index]>>;
+};
+
+/**
+ * Two phased approach for resolving promises:
+ * - first wait `resolveTimeoutMs` or until all promises settle
+ * - then wait `raceTimeoutMs - resolveTimeoutMs` or until at least a single promise resolves
+ *
+ * Returns a list of promise results, see `PromiseResult`
+ */
+export async function resolveOrRacePromises<T extends NonEmptyArray<PromiseLike<unknown>>>(
+  promises: T,
+  {
+    resolveTimeoutMs,
+    raceTimeoutMs,
+    signal,
+  }: {
+    resolveTimeoutMs: number;
+    raceTimeoutMs: number;
+    signal?: AbortSignal;
+  }
+): Promise<ReturnPromiseWithTuple<T>> | never {
+  if (raceTimeoutMs <= resolveTimeoutMs) {
+    throw new Error("Race time must be greater than resolve time");
+  }
+  const resolveTimeoutError = new TimeoutError(
+    `Given promises can't be resolved within resolveTimeoutMs=${resolveTimeoutMs}`
+  );
+  const raceTimeoutError = new TimeoutError(
+    `Not a any single promise be resolved in given raceTimeoutMs=${raceTimeoutMs}`
+  );
+
+  const promiseResults = promises.map((p) => wrapPromise(p)) as ReturnPromiseWithTuple<T>;
+  // We intentionally want an array of promises here
+  promises = (promiseResults as PromiseResult<T>[]).map((p) => p.promise) as unknown as T;
+
+  try {
+    await Promise.race([
+      Promise.allSettled(promises),
+      sleep(resolveTimeoutMs, signal).then(() => {
+        throw resolveTimeoutError;
+      }),
+    ]);
+
+    return promiseResults;
+  } catch (err) {
+    if (err instanceof ErrorAborted) {
+      return promiseResults;
+    }
+    if (err !== resolveTimeoutError) {
+      throw err;
+    }
+  }
+
+  try {
+    await Promise.race([
+      Promise.any(promises),
+      sleep(raceTimeoutMs - resolveTimeoutMs, signal).then(() => {
+        throw raceTimeoutError;
+      }),
+    ]);
+
+    return promiseResults;
+  } catch (err) {
+    if (err instanceof ErrorAborted) {
+      return promiseResults;
+    }
+    if (err !== raceTimeoutError && !(err instanceof AggregateError)) {
+      throw err;
+    }
+  }
+
+  return promiseResults;
+}

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);
+}