@aztec-labs/foundation 6.0.0-nightly.20260829

package/src/collection/array.ts

@@ -0,0 +1,351 @@
+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;
+}
+
+/**
+ * Filters an array with an async predicate. Fires all predicate promises in parallel.
+ * @param arr - The array to filter.
+ * @param fn - The async function to determine if an item should be included.
+ * @returns A promise that resolves to the filtered array.
+ */
+export async function filterAsync<T>(arr: T[], fn: (item: T) => Promise<boolean>): Promise<T[]> {
+  const results = await Promise.all(arr.map(fn));
+  return arr.filter((_, i) => results[i]);
+}
+
+/**
+ * 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 duplicates from the given array using a key function. The first occurrence of each key is kept.
+ * @param arr - The array.
+ * @param keyFn - A function that returns a primitive key for each element. Elements with the same key are
+ *               considered duplicates.
+ * @returns A new array.
+ */
+export function uniqueBy<T, K extends string | number | bigint>(arr: T[], keyFn: (item: T) => K): T[] {
+  const seen = new Set<K>();
+  const result: T[] = [];
+  for (const item of arr) {
+    const key = keyFn(item);
+    if (!seen.has(key)) {
+      seen.add(key);
+      result.push(item);
+    }
+  }
+  return result;
+}
+
+/**
+ * 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 | bigint): 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[]): number | undefined;
+/** Computes the median of a bigint array. Returns undefined if array is empty. */
+export function median(arr: bigint[]): bigint | undefined;
+export function median(arr: number[] | bigint[]): number | bigint | undefined {
+  if (arr.length === 0) {
+    return undefined;
+  }
+
+  // Handle number array
+  if (typeof arr[0] === 'number') {
+    const sorted = [...(arr as number[])].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;
+  }
+
+  // Handle bigint array
+  const sorted = [...(arr as bigint[])].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 !== 0 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2n;
+}
+
+/** 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)!);
+}
+
+/** Counts how many items from the beginning of the array match the given predicate. */
+export function countWhile<T>(collection: T[], predicate: (x: T) => boolean): number {
+  let count = 0;
+  for (const item of collection) {
+    if (predicate(item)) {
+      count++;
+    } else {
+      break;
+    }
+  }
+  return count;
+}
+
+/** Splits the given iterable into chunks of the given size. Last chunk may be of smaller than the requested size. */
+export function chunk<T>(items: T[], chunkSize: number): T[][] {
+  if (chunkSize <= 0) {
+    throw new Error('Chunk size must be greater than 0');
+  }
+  const chunks: T[][] = [];
+  for (let i = 0; i < items.length; i += chunkSize) {
+    chunks.push(items.slice(i, i + chunkSize));
+  }
+  return chunks;
+}
+
+/**
+ * Splits the given array into chunks of the given size, wrapping around to the beginning
+ * if the last chunk would be smaller than the requested size.
+ * Returns empty array for empty input. Returns single chunk with all items if chunkSize <= 0.
+ */
+export function chunkWrapAround<T>(items: T[], chunkSize: number): T[][] {
+  if (items.length === 0) {
+    return [];
+  }
+  if (chunkSize <= 0 || items.length <= chunkSize) {
+    return [items];
+  }
+  const remainder = items.length % chunkSize;
+  if (remainder === 0) {
+    return chunk(items, chunkSize);
+  }
+  const wrapAroundCount = chunkSize - remainder;
+  const wrappedItems = [...items, ...items.slice(0, wrapAroundCount)];
+  return chunk(wrappedItems, chunkSize);
+}
+
+const UNINITIALIZED = Symbol('uninitialized');
+
+/**
+ * Splits the given iterable into chunks based on the key returned by the given function.
+ * Items must be contiguous to be included in the same chunk.
+ */
+export function chunkBy<T, U>(items: T[], fn: (item: T) => U): T[][] {
+  const chunks: T[][] = [];
+  let currentChunk: T[] = [];
+  let currentKey: U | typeof UNINITIALIZED = UNINITIALIZED;
+
+  for (const item of items) {
+    const key = fn(item);
+    if (currentKey === UNINITIALIZED || key !== currentKey) {
+      if (currentChunk.length > 0) {
+        chunks.push(currentChunk);
+      }
+      currentChunk = [item];
+      currentKey = key;
+    } else {
+      currentChunk.push(item);
+    }
+  }
+
+  if (currentChunk.length > 0) {
+    chunks.push(currentChunk);
+  }
+
+  return chunks;
+}
+
+/** Partitions the given iterable into two arrays based on the predicate. */
+export function partition<T>(items: T[], predicate: (item: T) => boolean): [T[], T[]] {
+  const pass: T[] = [];
+  const fail: T[] = [];
+  for (const item of items) {
+    if (predicate(item)) {
+      pass.push(item);
+    } else {
+      fail.push(item);
+    }
+  }
+  return [pass, fail];
+}
+
+/** Partitions the given iterable into two arrays based on the predicate. */
+export async function partitionAsync<T>(items: T[], predicate: (item: T) => Promise<boolean>): Promise<[T[], T[]]> {
+  const pass: T[] = [];
+  const fail: T[] = [];
+  for (const item of items) {
+    if (await predicate(item)) {
+      pass.push(item);
+    } else {
+      fail.push(item);
+    }
+  }
+  return [pass, fail];
+}

package/src/collection/index.ts

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

package/src/collection/lru_map.ts

@@ -0,0 +1,143 @@
+/** Node in a doubly-linked list used by {@link LruMap}. */
+type LruNode<K, V> = {
+  key: K;
+  value: V;
+  prev: LruNode<K, V> | undefined;
+  next: LruNode<K, V> | undefined;
+};
+
+/**
+ * A bounded key-value map with Least Recently Used (LRU) eviction.
+ * Both {@link get} and {@link set} count as an access and refresh the entry's
+ * recency, so entries that are actively used stay in the map longest.
+ *
+ * Uses a doubly-linked list for O(1) ordering and a Map for O(1) lookup.
+ * Head = least recent, tail = most recent.
+ */
+export class LruMap<K, V> {
+  /** Map from key to its linked-list node for O(1) lookup. */
+  private readonly map = new Map<K, LruNode<K, V>>();
+  private head: LruNode<K, V> | undefined;
+  private tail: LruNode<K, V> | undefined;
+
+  constructor(private readonly maxSize: number) {
+    if (maxSize < 1) {
+      throw new Error('LruMap maxSize must be at least 1');
+    }
+  }
+
+  /** Number of entries in the map. */
+  get size(): number {
+    return this.map.size;
+  }
+
+  /** Returns true if the key is present, without refreshing its recency. */
+  has(key: K): boolean {
+    return this.map.has(key);
+  }
+
+  /**
+   * Returns the value for the key, or undefined if absent.
+   * Refreshes the entry's recency so it becomes the most recently used.
+   */
+  get(key: K): V | undefined {
+    const node = this.map.get(key);
+    if (!node) {
+      return undefined;
+    }
+    this.moveToTail(node);
+    return node.value;
+  }
+
+  /**
+   * Stores a value for the key, refreshing its recency. If the key already exists, overwrites the value.
+   * If the map is at capacity, evicts the least recently used entry.
+   */
+  set(key: K, value: V): void {
+    const existing = this.map.get(key);
+    if (existing) {
+      existing.value = value;
+      this.moveToTail(existing);
+      return;
+    }
+
+    if (this.map.size >= this.maxSize) {
+      this.evictHead();
+    }
+
+    const node: LruNode<K, V> = { key, value, prev: this.tail, next: undefined };
+    if (this.tail) {
+      this.tail.next = node;
+    } else {
+      this.head = node;
+    }
+    this.tail = node;
+    this.map.set(key, node);
+  }
+
+  /** Removes the entry for the key, returning true if it was present. */
+  delete(key: K): boolean {
+    const node = this.map.get(key);
+    if (!node) {
+      return false;
+    }
+    this.unlink(node);
+    this.map.delete(key);
+    return true;
+  }
+
+  /** Removes all entries from the map. */
+  clear(): void {
+    this.map.clear();
+    this.head = undefined;
+    this.tail = undefined;
+  }
+
+  /** Unlinks a node from its current position and relinks it at the tail. */
+  private moveToTail(node: LruNode<K, V>): void {
+    if (node === this.tail) {
+      return;
+    }
+    this.unlink(node);
+
+    node.prev = this.tail;
+    node.next = undefined;
+    if (this.tail) {
+      this.tail.next = node;
+    } else {
+      this.head = node;
+    }
+    this.tail = node;
+  }
+
+  /** Detaches a node from the linked list, fixing up its neighbours and the head/tail pointers. */
+  private unlink(node: LruNode<K, V>): void {
+    if (node.prev) {
+      node.prev.next = node.next;
+    } else {
+      this.head = node.next;
+    }
+    if (node.next) {
+      node.next.prev = node.prev;
+    } else {
+      this.tail = node.prev;
+    }
+    node.prev = undefined;
+    node.next = undefined;
+  }
+
+  /** Evicts the head (least recently used) node. */
+  private evictHead(): void {
+    const oldHead = this.head;
+    if (!oldHead) {
+      return;
+    }
+    this.head = oldHead.next;
+    if (this.head) {
+      this.head.prev = undefined;
+    } else {
+      this.tail = undefined;
+    }
+    this.map.delete(oldHead.key);
+  }
+}

package/src/collection/lru_set.ts

@@ -0,0 +1,115 @@
+/** Node in a doubly-linked list used by {@link LruSet}. */
+type LruNode<T> = {
+  value: T;
+  prev: LruNode<T> | undefined;
+  next: LruNode<T> | undefined;
+};
+
+/**
+ * A bounded set with Least Recently Used (LRU) eviction.
+ * Both {@link has} and {@link add} count as an access and refresh the entry's
+ * recency, so items that are actively checked stay in the set longest.
+ *
+ * Uses a doubly-linked list for O(1) ordering and a Map for O(1) lookup.
+ * Head = least recent, tail = most recent.
+ */
+export class LruSet<T> {
+  /** Map from value to its linked-list node for O(1) lookup. */
+  private readonly map = new Map<T, LruNode<T>>();
+  private head: LruNode<T> | undefined;
+  private tail: LruNode<T> | undefined;
+
+  constructor(private readonly maxSize: number) {
+    if (maxSize < 1) {
+      throw new Error('LruSet maxSize must be at least 1');
+    }
+  }
+
+  /** Number of entries in the set. */
+  get size(): number {
+    return this.map.size;
+  }
+
+  /**
+   * Returns true if the item is in the set.
+   * Refreshes the item's recency so it becomes the most recently used.
+   */
+  has(item: T): boolean {
+    const node = this.map.get(item);
+    if (!node) {
+      return false;
+    }
+    this.moveToTail(node);
+    return true;
+  }
+
+  /**
+   * Adds an item to the set. If the item already exists, refreshes its recency.
+   * If the set is at capacity, evicts the least recently used item.
+   */
+  add(item: T): void {
+    const existing = this.map.get(item);
+    if (existing) {
+      this.moveToTail(existing);
+      return;
+    }
+
+    if (this.map.size >= this.maxSize) {
+      this.evictHead();
+    }
+
+    const node: LruNode<T> = { value: item, prev: this.tail, next: undefined };
+    if (this.tail) {
+      this.tail.next = node;
+    } else {
+      this.head = node;
+    }
+    this.tail = node;
+    this.map.set(item, node);
+  }
+
+  /** Removes all entries from the set. */
+  clear(): void {
+    this.map.clear();
+    this.head = undefined;
+    this.tail = undefined;
+  }
+
+  /** Unlinks a node from its current position and relinks it at the tail. */
+  private moveToTail(node: LruNode<T>): void {
+    if (node === this.tail) {
+      return;
+    }
+
+    // Unlink
+    if (node.prev) {
+      node.prev.next = node.next;
+    } else {
+      this.head = node.next;
+    }
+    if (node.next) {
+      node.next.prev = node.prev;
+    }
+
+    // Relink at tail
+    node.prev = this.tail;
+    node.next = undefined;
+    if (this.tail) {
+      this.tail.next = node;
+    }
+    this.tail = node;
+  }
+
+  /** Evicts the head (least recently used) node. */
+  private evictHead(): void {
+    const oldHead = this.head!;
+    this.map.delete(oldHead.value);
+
+    this.head = oldHead.next;
+    if (this.head) {
+      this.head.prev = undefined;
+    } else {
+      this.tail = undefined;
+    }
+  }
+}

package/src/collection/object.ts

@@ -0,0 +1,89 @@
+/** 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;
+}
+
+/** Equivalent to Object.keys but preserves types. */
+export function getKeys<T extends object>(obj: T): (keyof T)[] {
+  return Object.keys(obj) as (keyof T)[];
+}
+
+/** Equivalent to Object.entries but preserves types. */
+export function getEntries<T extends Record<PropertyKey, unknown>>(obj: T): { [K in keyof T]: [K, T[K]] }[keyof T][] {
+  // See https://stackoverflow.com/a/76176570
+  return Object.entries(obj) as { [K in keyof T]: [K, T[K]] }[keyof T][];
+}
+
+/** Equivalent to Object.fromEntries but preserves types. */
+export function fromEntries<const T extends ReadonlyArray<readonly [PropertyKey, unknown]>>(
+  entries: T,
+): { [K in T[number] as K[0]]: K[1] } {
+  // See https://stackoverflow.com/a/76176570
+  return Object.fromEntries(entries) as { [K in T[number] as K[0]]: K[1] };
+}
+
+/** Asserts all values in object are not undefined. */
+export function assertRequired<T extends object>(obj: T): Required<T> {
+  for (const key in obj) {
+    if (obj[key] === undefined) {
+      throw new Error(`Missing property ${key}`);
+    }
+  }
+  return obj as Required<T>;
+}
+
+/** Returns the result of merging two objects ignoring properties with undefined values. */
+export function merge<T extends object, U extends object>(
+  obj1: T,
+  obj2: U | undefined,
+): T & { [P in keyof U]+?: Exclude<U[P], undefined> } {
+  return { ...obj1, ...compact(obj2 ?? {}) };
+}