@aztec/foundation 0.0.0-test.0

package/src/async-pool/index.ts

@@ -0,0 +1,50 @@
+/*
+ * Adapted from https://github.com/rxaviers/async-pool/blob/1.x/lib/es6.js
+ *
+ * Copyright (c) 2017 Rafael Xavier de Souza http://rafael.xavier.blog.br
+ *
+ * Permission is hereby granted, free of charge, to any person
+ * obtaining a copy of this software and associated documentation
+ * files (the "Software"), to deal in the Software without
+ * restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the
+ * Software is furnished to do so, subject to the following
+ * conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+ * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+ * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+ * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+ * OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+/** Executes the given async function over the iterable, up to a determined number of promises in parallel. */
+export function asyncPool<T, R>(poolLimit: number, iterable: T[], iteratorFn: (item: T, iterable: T[]) => Promise<R>) {
+  let i = 0;
+  const ret: Promise<R>[] = [];
+  const executing: Set<Promise<R>> = new Set();
+  const enqueue = (): Promise<any> => {
+    if (i === iterable.length) {
+      return Promise.resolve();
+    }
+    const item = iterable[i++];
+    const p = Promise.resolve().then(() => iteratorFn(item, iterable));
+    ret.push(p);
+    executing.add(p);
+    const clean = () => executing.delete(p);
+    p.then(clean).catch(clean);
+    let r: Promise<any> = Promise.resolve();
+    if (executing.size >= poolLimit) {
+      r = Promise.race(executing);
+    }
+    return r.then(() => enqueue());
+  };
+  return enqueue().then(() => Promise.all(ret));
+}

package/src/bigint-buffer/index.ts

@@ -0,0 +1,87 @@
+/**
+ * Convert a little-endian buffer into a BigInt.
+ * @param buf - The little-endian buffer to convert.
+ * @returns A BigInt with the little-endian representation of buf.
+ */
+export function toBigIntLE(buf: Buffer): bigint {
+  const reversed = Buffer.from(buf);
+  reversed.reverse();
+  const hex = reversed.toString('hex');
+  if (hex.length === 0) {
+    return BigInt(0);
+  }
+  return BigInt(`0x${hex}`);
+}
+
+/**
+ * Convert a big-endian buffer into a BigInt.
+ * @param buf - The big-endian buffer to convert.
+ * @returns A BigInt with the big-endian representation of buf.
+ */
+export function toBigIntBE(buf: Buffer): bigint {
+  const hex = buf.toString('hex');
+  if (hex.length === 0) {
+    return BigInt(0);
+  }
+  return BigInt(`0x${hex}`);
+}
+
+/**
+ * Convert a BigInt to a little-endian buffer.
+ * @param num - The BigInt to convert.
+ * @param width - The number of bytes that the resulting buffer should be.
+ * @returns A little-endian buffer representation of num.
+ */
+export function toBufferLE(num: bigint, width: number): Buffer {
+  if (num < BigInt(0)) {
+    throw new Error(`Cannot convert negative bigint ${num.toString()} to buffer with toBufferLE.`);
+  }
+  const hex = num.toString(16);
+  const buffer = Buffer.from(hex.padStart(width * 2, '0').slice(0, width * 2), 'hex');
+  buffer.reverse();
+  return buffer;
+}
+
+/**
+ * Convert a BigInt to a big-endian buffer.
+ * @param num - The BigInt to convert.
+ * @param width - The number of bytes that the resulting buffer should be.
+ * @returns A big-endian buffer representation of num.
+ */
+export function toBufferBE(num: bigint, width: number): Buffer {
+  if (num < BigInt(0)) {
+    throw new Error(`Cannot convert negative bigint ${num.toString()} to buffer with toBufferBE.`);
+  }
+  const hex = num.toString(16);
+  const buffer = Buffer.from(hex.padStart(width * 2, '0').slice(0, width * 2), 'hex');
+  if (buffer.length > width) {
+    throw new Error(`Number ${num.toString(16)} does not fit in ${width}`);
+  }
+  return buffer;
+}
+
+/**
+ * Converts a BigInt to its hex representation.
+ * @param num - The BigInt to convert.
+ * @param padTo32 - Whether to pad the resulting string to 32 bytes.
+ * @returns An even-length 0x-prefixed string.
+ */
+export function toHex(num: bigint, padTo32 = false): `0x${string}` {
+  const str = num.toString(16);
+  const targetLen = str.length % 2 === 0 ? str.length : str.length + 1;
+  const paddedStr = str.padStart(padTo32 ? 64 : targetLen, '0');
+  return `0x${paddedStr}`;
+}
+
+/**
+ * Converts a hex string to a buffer. Throws if input is not a valid hex string.
+ * @param value - The hex string to convert. May be 0x prefixed or not.
+ * @returns A buffer.
+ */
+export function fromHex(value: string): Buffer {
+  const hexRegex = /^(0x)?[0-9a-fA-F]*$/;
+  if (!hexRegex.test(value) || value.length % 2 !== 0) {
+    throw new Error(`Invalid hex string: ${value}`);
+  }
+  return Buffer.from(value.replace(/^0x/i, ''), 'hex');
+}

package/src/buffer/buffer32.ts

@@ -0,0 +1,144 @@
+import { randomBytes } from '@aztec/foundation/crypto';
+import type { Fr } from '@aztec/foundation/fields';
+import { BufferReader, deserializeBigInt, serializeBigInt } from '@aztec/foundation/serialize';
+
+import { bufferToHex } from '../string/index.js';
+
+/**
+ * A class representing a 32 byte Buffer.
+ */
+export class Buffer32 {
+  /**
+   * The size of the hash in bytes.
+   */
+  public static SIZE = 32;
+
+  /**
+   * Buffer32 with value zero.
+   */
+  public static ZERO = new Buffer32(Buffer.alloc(Buffer32.SIZE));
+
+  constructor(
+    /**
+     * The buffer containing the hash.
+     */
+    public buffer: Buffer,
+  ) {
+    if (buffer.length !== Buffer32.SIZE) {
+      throw new Error(`Expected buffer to have length ${Buffer32.SIZE} but was ${buffer.length}`);
+    }
+  }
+
+  /**
+   * Returns the raw buffer of the hash.
+   * @returns The buffer containing the hash.
+   */
+  public toBuffer() {
+    return this.buffer;
+  }
+
+  /**
+   * Creates a Buffer32 from a buffer.
+   * @param buffer - The buffer to create from.
+   * @returns A new Buffer32 object.
+   */
+  public static fromBuffer(buffer: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(buffer);
+    return new Buffer32(reader.readBytes(Buffer32.SIZE));
+  }
+
+  /**
+   * Checks if this hash and another hash are equal.
+   * @param hash - A hash to compare with.
+   * @returns True if the hashes are equal, false otherwise.
+   */
+  public equals(hash: Buffer32): boolean {
+    return this.buffer.equals(hash.buffer);
+  }
+
+  /**
+   * Returns true if this hash is zero.
+   * @returns True if this hash is zero.
+   */
+  public isZero(): boolean {
+    return this.buffer.equals(Buffer.alloc(32, 0));
+  }
+
+  /**
+   * Convert this hash to a hex string.
+   * @returns The hex string.
+   */
+  public toString() {
+    return bufferToHex(this.buffer);
+  }
+
+  toJSON() {
+    return this.toString();
+  }
+
+  /**
+   * Convert this hash to a big int.
+   * @returns The big int.
+   */
+  public toBigInt() {
+    return deserializeBigInt(this.buffer, 0, Buffer32.SIZE).elem;
+  }
+  /**
+   * Creates a Buffer32 from a bigint.
+   * @param hash - The tx hash as a big int.
+   * @returns The Buffer32.
+   */
+  public static fromBigInt(hash: bigint) {
+    return new Buffer32(serializeBigInt(hash, Buffer32.SIZE));
+  }
+
+  public static fromField(hash: Fr) {
+    return new Buffer32(serializeBigInt(hash.toBigInt()));
+  }
+
+  /**
+   * Converts this hash from a buffer of 28 bytes.
+   * Verifies the input is 28 bytes.
+   * @param buffer - The 28 byte buffer to construct from.
+   * @returns A Buffer32 created from the input buffer with 4 bytes 0 padding at the front.
+   */
+  public static fromBuffer28(buffer: Buffer) {
+    if (buffer.length != 28) {
+      throw new Error(`Expected Buffer32 input buffer to be 28 bytes`);
+    }
+    const padded = Buffer.concat([Buffer.alloc(this.SIZE - 28), buffer]);
+    return new Buffer32(padded);
+  }
+
+  /**
+   * Converts a string into a Buffer32 object.
+   * @param str - The TX hash in string format.
+   * @returns A new Buffer32 object.
+   */
+  public static fromString(str: string): Buffer32 {
+    if (str.startsWith('0x')) {
+      str = str.slice(2);
+    }
+    if (str.length !== 64) {
+      throw new Error(`Expected string to be 64 characters long, but was ${str.length}`);
+    }
+    return new Buffer32(Buffer.from(str, 'hex'));
+  }
+
+  /**
+   * Converts a number into a Buffer32 object.
+   * @param num - The number to convert.
+   * @returns A new Buffer32 object.
+   */
+  public static fromNumber(num: number): Buffer32 {
+    return new Buffer32(serializeBigInt(BigInt(num), Buffer32.SIZE));
+  }
+
+  /**
+   * Generates a random Buffer32.
+   * @returns A new Buffer32 object.
+   */
+  public static random(): Buffer32 {
+    return new Buffer32(Buffer.from(randomBytes(Buffer32.SIZE)));
+  }
+}

package/src/buffer/index.ts

@@ -0,0 +1 @@
+export * from './buffer32.js';

package/src/collection/array.ts

@@ -0,0 +1,203 @@
+import type { Tuple } from '../serialize/types.js';
+
+/**
+ * Pads an array to the target length by appending an element to its end. Throws if target length exceeds the input array length. Does not modify the input array.
+ * @param arr - Array with elements to pad.
+ * @param elem - Element to use for padding.
+ * @param length - Target length.
+ * @param errorMsg - Error message to throw if target length exceeds the input array length.
+ * @returns A new padded array.
+ */
+export function padArrayEnd<T, N extends number>(
+  arr: T[],
+  elem: T,
+  length: N,
+  errorMsg = 'Array size exceeds target length',
+): Tuple<T, N> {
+  if (arr.length > length) {
+    throw new Error(errorMsg);
+  }
+  // Since typescript cannot always deduce that something is a tuple, we cast
+  return [...arr, ...Array(length - arr.length).fill(elem)] as Tuple<T, N>;
+}
+
+/** Removes the right-padding for an array. Does not modify original array. */
+export function removeArrayPaddingEnd<T>(arr: T[], isEmpty: (item: T) => boolean): T[] {
+  const lastNonEmptyIndex = arr.reduce((last, item, i) => (isEmpty(item) ? last : i), -1);
+  return lastNonEmptyIndex === -1 ? [] : arr.slice(0, lastNonEmptyIndex + 1);
+}
+
+/**
+ * Pads an array to the target length by prepending elements at the beginning. Throws if target length exceeds the input array length. Does not modify the input array.
+ * @param arr - Array with elements to pad.
+ * @param elem - Element to use for padding.
+ * @param length - Target length.
+ * @returns A new padded array.
+ */
+export function padArrayStart<T, N extends number>(arr: T[], elem: T, length: N): Tuple<T, N> {
+  if (arr.length > length) {
+    throw new Error(`Array size exceeds target length`);
+  }
+  // Since typescript cannot always deduce that something is a tuple, we cast
+  return [...Array(length - arr.length).fill(elem), ...arr] as Tuple<T, N>;
+}
+
+/**
+ * Returns if an array is composed of empty items.
+ * @param arr - Array to check.
+ * @returns True if every item in the array isEmpty.
+ */
+export function isArrayEmpty<T>(arr: T[], isEmpty: (item: T) => boolean): boolean {
+  for (const item of arr) {
+    if (!isEmpty(item)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Returns the number of non-empty items in an array.
+ * @param arr - Array to check.
+ * @returns Number of non-empty items in an array.
+ */
+export function arrayNonEmptyLength<T>(arr: T[], isEmpty: (item: T) => boolean): number {
+  return arr.reduce((sum, item) => (isEmpty(item) ? sum : sum + 1), 0);
+}
+
+/**
+ * Executes the given function n times and returns the results in an array.
+ * @param n - How many times to repeat.
+ * @param fn - Mapper from index to value.
+ * @returns The array with the result from all executions.
+ */
+export function times<T>(n: number, fn: (i: number) => T): T[] {
+  return [...Array(n).keys()].map(i => fn(i));
+}
+
+/**
+ * Executes the given async function n times and returns the results in an array. Awaits each execution before starting the next one.
+ * @param n - How many times to repeat.
+ * @param fn - Mapper from index to value.
+ * @returns The array with the result from all executions.
+ */
+export async function timesAsync<T>(n: number, fn: (i: number) => Promise<T>): Promise<T[]> {
+  const results: T[] = [];
+  for (let i = 0; i < n; i++) {
+    results.push(await fn(i));
+  }
+  return results;
+}
+
+/**
+ * Executes the given async function n times in parallel and returns the results in an array.
+ * @param n - How many times to repeat.
+ * @param fn - Mapper from index to value.
+ * @returns The array with the result from all executions.
+ */
+export async function timesParallel<T>(n: number, fn: (i: number) => Promise<T>): Promise<T[]> {
+  const results: T[] = await Promise.all(
+    Array(n)
+      .fill(0)
+      .map((_, i) => fn(i)),
+  );
+  return results;
+}
+
+/**
+ * Returns the serialized size of all non-empty items in an array.
+ * @param arr - Array
+ * @returns The serialized size in bytes.
+ */
+export function arraySerializedSizeOfNonEmpty(
+  arr: (({ isZero: () => boolean } | { isEmpty: () => boolean }) & { toBuffer: () => Buffer })[],
+) {
+  return arr
+    .filter(x => x && ('isZero' in x ? !x.isZero() : !x.isEmpty()))
+    .map(x => x!.toBuffer().length)
+    .reduce((a, b) => a + b, 0);
+}
+
+/**
+ * Removes duplicates from the given array.
+ * @param arr - The array.
+ * @returns A new array.
+ */
+export function unique<T>(arr: T[]): T[] {
+  return [...new Set(arr)];
+}
+
+/**
+ * Removes all undefined elements from the array.
+ * @param arr - The array.
+ * @returns A new array.
+ */
+export function compactArray<T>(arr: (T | undefined)[]): T[] {
+  return arr.filter((x: T | undefined): x is T => x !== undefined);
+}
+
+/**
+ * Returns whether two arrays are equal. The arrays are equal if they have the same length and all elements are equal.
+ */
+export function areArraysEqual<T>(a: T[], b: T[], eq: (a: T, b: T) => boolean = (a: T, b: T) => a === b): boolean {
+  if (a.length !== b.length) {
+    return false;
+  }
+  for (let i = 0; i < a.length; i++) {
+    if (!eq(a[i], b[i])) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Returns the element of the array that has the maximum value of the given function.
+ * In case of a tie, returns the first element with the maximum value.
+ * @param arr - The array.
+ * @param fn - The function to get the value to compare.
+ */
+export function maxBy<T>(arr: T[], fn: (x: T) => number): T | undefined {
+  return arr.reduce((max, x) => (fn(x) > fn(max) ? x : max), arr[0]);
+}
+
+/** Computes the sum of a numeric array. */
+export function sum(arr: number[]): number {
+  return arr.reduce((a, b) => a + b, 0);
+}
+
+/** Computes the median of a numeric array. Returns undefined if array is empty. */
+export function median(arr: number[]) {
+  if (arr.length === 0) {
+    return undefined;
+  }
+  const sorted = [...arr].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 !== 0 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+
+/** Computes the mean of a numeric array. Returns undefined if the array is empty. */
+export function mean(values: number[]) {
+  if (values.length === 0) {
+    return undefined;
+  }
+  return values.reduce((a, b) => a + b, 0) / values.length;
+}
+
+/** Computes the variance of a numeric array. Returns undefined if there are less than 2 points. */
+export function variance(values: number[]) {
+  if (values.length < 2) {
+    return undefined;
+  }
+  const avg = mean(values)!;
+  const points = values.map(value => value * value + avg * avg - 2 * value * avg);
+  return sum(points) / (values.length - 1);
+}
+
+/** Computes the standard deviation of a numeric array. Returns undefined if there are less than 2 points. */
+export function stdDev(values: number[]) {
+  if (values.length < 2) {
+    return undefined;
+  }
+  return Math.sqrt(variance(values)!);
+}

package/src/collection/index.ts

@@ -0,0 +1,2 @@
+export * from './array.js';
+export * from './object.js';

package/src/collection/object.ts

@@ -0,0 +1,52 @@
+/** Returns a new object with the same keys and where each value has been passed through the mapping function. */
+export function mapValues<K extends string | number | symbol, T, U>(
+  obj: Record<K, T>,
+  fn: (value: T, key: K) => U,
+): Record<K, U>;
+export function mapValues<K extends string | number | symbol, T, U>(
+  obj: Partial<Record<K, T>>,
+  fn: (value: T, key: K) => U,
+): Partial<Record<K, U>>;
+export function mapValues<K extends string | number | symbol, T, U>(
+  obj: Record<K, T>,
+  fn: (value: T, key: K) => U,
+): Record<K, U> {
+  const result: Record<K, U> = {} as Record<K, U>;
+  for (const key in obj) {
+    result[key] = fn(obj[key], key);
+  }
+  return result;
+}
+
+/** Returns a new object where all keys with undefined values have been removed. */
+export function compact<T extends object>(obj: T): { [P in keyof T]+?: Exclude<T[P], undefined> } {
+  const result: any = {};
+  for (const key in obj) {
+    if (obj[key] !== undefined) {
+      result[key] = obj[key];
+    }
+  }
+  return result;
+}
+
+/** Returns a new object by picking the given keys. */
+export function pick<T extends object, U extends keyof T>(object: T, ...props: U[]): Pick<T, U>;
+export function pick<T extends object>(object: T, ...props: string[]): Partial<T>;
+export function pick<T extends object>(object: T, ...props: string[]): Partial<T> {
+  const obj: any = {};
+  for (const prop of props) {
+    obj[prop] = (object as any)[prop];
+  }
+  return obj;
+}
+
+/** Returns a new object by omitting the given keys. */
+export function omit<T extends object, K extends keyof T>(object: T, ...props: K[]): Omit<T, K>;
+export function omit<T extends object>(object: T, ...props: string[]): Partial<T>;
+export function omit<T extends object>(object: T, ...props: string[]): Partial<T> {
+  const obj: any = { ...object };
+  for (const prop of props) {
+    delete obj[prop];
+  }
+  return obj;
+}

package/src/committable/committable.ts

@@ -0,0 +1,46 @@
+/**
+ * A class that allows for a value to be committed or rolled back.
+ */
+export class Committable<T> {
+  private currentValue: T;
+  private nextValue: T | undefined = undefined;
+
+  constructor(initialValue: T) {
+    this.currentValue = initialValue;
+  }
+
+  /**
+   * Commits the uncommitted value.
+   */
+  public commit() {
+    if (this.nextValue === undefined) {
+      return;
+    }
+    this.currentValue = this.nextValue;
+    this.nextValue = undefined;
+  }
+
+  /**
+   * Rolls back the uncommitted value.
+   */
+  public rollback() {
+    this.nextValue === undefined;
+  }
+
+  /**
+   * Gets the current value.
+   * @param includeUncommitted - Whether to include the uncommitted value.
+   * @returns The current value if includeUncommitted is false, otherwise the uncommitted value.
+   */
+  public get(includeUncommitted: boolean = false): T {
+    return includeUncommitted && this.nextValue ? this.nextValue : this.currentValue;
+  }
+
+  /**
+   * Sets the next value to be committed to.
+   * @param value - The new value to be set.
+   */
+  public set(value: T) {
+    this.nextValue = value;
+  }
+}

package/src/committable/index.ts

@@ -0,0 +1 @@
+export * from './committable.js';