@aztec/foundation 0.0.0-test.1 → 0.0.1-commit.017a351

package/src/branded-types/slot.ts

@@ -0,0 +1,93 @@
+import { z } from 'zod';
+
+import type { Branded } from './types.js';
+
+/**
+ * A branded type representing a slot number.
+ * Slots are the fundamental time unit in the Aztec protocol, with multiple slots comprising an epoch.
+ *
+ * This is a nominal type backed by a number, but TypeScript will treat it as
+ * incompatible with plain numbers and other branded numeric types (like EpochNumber, BlockNumber, etc.).
+ *
+ * @example
+ * ```ts
+ * const slot = SlotNumber(5);
+ * const plainNumber: number = slot; // OK - SlotNumber is assignable to number
+ * const slotFromNumber: SlotNumber = 5;  // ERROR - number is not assignable to SlotNumber
+ * ```
+ */
+export type SlotNumber = Branded<number, 'SlotNumber'>;
+
+/**
+ * Creates a SlotNumber from a number.
+ * @param value - The slot number (must be a non-negative integer)
+ * @returns The branded SlotNumber value
+ * @throws If the value is negative or not an integer
+ */
+export function SlotNumber(value: number): SlotNumber {
+  if (!Number.isInteger(value)) {
+    throw new Error(`SlotNumber must be an integer, got ${value}`);
+  }
+  if (value < 0) {
+    throw new Error(`SlotNumber must be non-negative, got ${value}`);
+  }
+  return value as SlotNumber;
+}
+
+/**
+ * Creates a SlotNumber from a bigint.
+ * @param value - The slot number as bigint (must be a non-negative integer within safe integer range)
+ * @returns The branded SlotNumber value
+ * @throws If the value is negative or exceeds Number.MAX_SAFE_INTEGER
+ */
+SlotNumber.fromBigInt = function (value: bigint): SlotNumber {
+  if (value < 0n) {
+    throw new Error(`SlotNumber must be non-negative, got ${value}`);
+  }
+  if (value > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new Error(`SlotNumber ${value} exceeds MAX_SAFE_INTEGER`);
+  }
+  return Number(value) as SlotNumber;
+};
+
+/**
+ * Creates a SlotNumber from a string.
+ * @param value - The slot number as a string
+ * @returns The branded SlotNumber value
+ * @throws If the string cannot be parsed as a valid slot
+ */
+SlotNumber.fromString = function (value: string): SlotNumber {
+  const parsed = parseInt(value, 10);
+  if (isNaN(parsed)) {
+    throw new Error(`Cannot parse SlotNumber from string: ${value}`);
+  }
+  return SlotNumber(parsed);
+};
+
+/**
+ * Type guard to check if a value is a valid SlotNumber.
+ * Note: At runtime, a SlotNumber is just a number, so this checks if the value
+ * is a non-negative integer.
+ */
+SlotNumber.isValid = function (value: unknown): value is SlotNumber {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 0;
+};
+
+/** Increments a SlotNumber by a given value. */
+SlotNumber.add = function (sn: SlotNumber, increment: number): SlotNumber {
+  return SlotNumber(sn + increment);
+};
+
+/**
+ * The zero slot value.
+ */
+SlotNumber.ZERO = SlotNumber(0);
+
+/**
+ * Zod schema for parsing and validating SlotNumber values.
+ * Accepts numbers, bigints, or strings and coerces them to SlotNumber.
+ */
+export const SlotNumberSchema = z
+  .union([z.number(), z.bigint(), z.string()])
+  .pipe(z.coerce.number<string | number | bigint>().int().min(0))
+  .transform(value => SlotNumber(value));

package/src/branded-types/types.ts

@@ -0,0 +1,2 @@
+/** Adds a branding to a type for nominal typing. */
+export type Branded<T, Brand> = T & { _branding: Brand };

package/src/buffer/buffer16.ts

@@ -0,0 +1,136 @@
+import { randomBytes } from '@aztec/foundation/crypto/random';
+import type { Fr } from '@aztec/foundation/curves/bn254';
+import { BufferReader, deserializeBigInt, serializeBigInt } from '@aztec/foundation/serialize';
+
+import { inspect } from 'util';
+
+import { bufferToHex } from '../string/index.js';
+
+/**
+ * A class representing a 16 byte Buffer.
+ */
+export class Buffer16 {
+  /** Branding for nominal typing. */
+  declare private readonly _branding: 'Buffer16';
+
+  /**
+   * The size of the hash in bytes.
+   */
+  public static SIZE = 16;
+
+  /**
+   * Buffer16 with value zero.
+   */
+  public static ZERO = new Buffer16(Buffer.alloc(Buffer16.SIZE));
+
+  constructor(
+    /**
+     * The buffer containing the hash.
+     */
+    public buffer: Buffer,
+  ) {
+    if (buffer.length !== Buffer16.SIZE) {
+      throw new Error(`Expected buffer to have length ${Buffer16.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 Buffer16 from a buffer.
+   * @param buffer - The buffer to create from.
+   * @returns A new Buffer16 object.
+   */
+  public static fromBuffer(buffer: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(buffer);
+    return new Buffer16(reader.readBytes(Buffer16.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: Buffer16): 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(16, 0));
+  }
+
+  /**
+   * Convert this hash to a hex string.
+   * @returns The hex string.
+   */
+  public toString() {
+    return bufferToHex(this.buffer);
+  }
+
+  [inspect.custom]() {
+    return `Buffer16<${this.toString()}>`;
+  }
+
+  toJSON() {
+    return this.toString();
+  }
+
+  /**
+   * Convert this hash to a big int.
+   * @returns The big int.
+   */
+  public toBigInt() {
+    return deserializeBigInt(this.buffer, 0, Buffer16.SIZE).elem;
+  }
+
+  /**
+   * Creates a Buffer16 from a bigint.
+   */
+  public static fromBigInt(hash: bigint) {
+    return new Buffer16(serializeBigInt(hash, Buffer16.SIZE));
+  }
+
+  public static fromField(hash: Fr) {
+    return new Buffer16(serializeBigInt(hash.toBigInt()));
+  }
+
+  /**
+   * Converts a hex string into a Buffer16 object.
+   */
+  public static fromString(str: string): Buffer16 {
+    if (str.startsWith('0x')) {
+      str = str.slice(2);
+    }
+    if (str.length !== this.SIZE * 2) {
+      throw new Error(`Expected string to be ${this.SIZE * 2} characters long, but was ${str.length}`);
+    }
+    return new Buffer16(Buffer.from(str, 'hex'));
+  }
+
+  /**
+   * Converts a number into a Buffer16 object.
+   * @param num - The number to convert.
+   * @returns A new Buffer16 object.
+   */
+  public static fromNumber(num: number): Buffer16 {
+    return new Buffer16(serializeBigInt(BigInt(num), Buffer16.SIZE));
+  }
+
+  /**
+   * Generates a random Buffer16.
+   * @returns A new Buffer16 object.
+   */
+  public static random(): Buffer16 {
+    return new Buffer16(Buffer.from(randomBytes(Buffer16.SIZE)));
+  }
+}

package/src/buffer/buffer32.ts

@@ -1,93 +1,78 @@
-import { randomBytes } from '@aztec/foundation/crypto';
-import type { Fr } from '@aztec/foundation/fields';
+import { randomBytes } from '@aztec/foundation/crypto/random';
+import type { Fr } from '@aztec/foundation/curves/bn254';
 import { BufferReader, deserializeBigInt, serializeBigInt } from '@aztec/foundation/serialize';
 
+import { inspect } from 'util';
+
 import { bufferToHex } from '../string/index.js';
 
 /**
- * A class representing a 32 byte Buffer.
+ * Abstract unbranded base class for 32-byte buffers.
+ * Extend this instead of Buffer32 when defining a branded subtype
+ * to avoid inheriting Buffer32's `_branding`.
  */
-export class Buffer32 {
-  /**
-   * The size of the hash in bytes.
-   */
+export abstract class BaseBuffer32 {
+  /** The size of the buffer 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.
-     */
+    /** The buffer containing the data. */
     public buffer: Buffer,
   ) {
-    if (buffer.length !== Buffer32.SIZE) {
-      throw new Error(`Expected buffer to have length ${Buffer32.SIZE} but was ${buffer.length}`);
+    if (buffer.length !== BaseBuffer32.SIZE) {
+      throw new Error(`Expected buffer to have length ${BaseBuffer32.SIZE} but was ${buffer.length}`);
     }
   }
 
-  /**
-   * Returns the raw buffer of the hash.
-   * @returns The buffer containing the hash.
-   */
+  /** Returns the raw buffer. */
   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 {
+  /** Checks if this and another buffer are equal. */
+  public equals(hash: BaseBuffer32): boolean {
     return this.buffer.equals(hash.buffer);
   }
 
-  /**
-   * Returns true if this hash is zero.
-   * @returns True if this hash is zero.
-   */
+  /** Returns true if all bytes are zero. */
   public isZero(): boolean {
     return this.buffer.equals(Buffer.alloc(32, 0));
   }
 
-  /**
-   * Convert this hash to a hex string.
-   * @returns The hex string.
-   */
+  /** Convert to a hex string. */
   public toString() {
     return bufferToHex(this.buffer);
   }
 
+  [inspect.custom]() {
+    return `Buffer32<${this.toString()}>`;
+  }
+
   toJSON() {
     return this.toString();
   }
 
-  /**
-   * Convert this hash to a big int.
-   * @returns The big int.
-   */
+  /** Convert to a big int. */
   public toBigInt() {
-    return deserializeBigInt(this.buffer, 0, Buffer32.SIZE).elem;
+    return deserializeBigInt(this.buffer, 0, BaseBuffer32.SIZE).elem;
   }
-  /**
-   * Creates a Buffer32 from a bigint.
-   * @param hash - The tx hash as a big int.
-   * @returns The Buffer32.
-   */
+}
+
+/** A branded 32-byte buffer. */
+export class Buffer32 extends BaseBuffer32 {
+  /** Branding for nominal typing. */
+  declare private readonly _branding: 'Buffer32';
+
+  /** Buffer32 with value zero. */
+  public static ZERO = new Buffer32(Buffer.alloc(Buffer32.SIZE));
+
+  /** Creates a Buffer32 from a buffer. */
+  public static fromBuffer(buffer: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(buffer);
+    return new Buffer32(reader.readBytes(Buffer32.SIZE));
+  }
+
+  /** Creates a Buffer32 from a bigint. */
   public static fromBigInt(hash: bigint) {
     return new Buffer32(serializeBigInt(hash, Buffer32.SIZE));
   }
@@ -97,8 +82,7 @@ export class Buffer32 {
   }
 
   /**
-   * Converts this hash from a buffer of 28 bytes.
-   * Verifies the input is 28 bytes.
+   * Converts from a buffer of 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.
    */
@@ -106,38 +90,27 @@ export class Buffer32 {
     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]);
+    const padded = Buffer.concat([Buffer.alloc(Buffer32.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.
-   */
+  /** Converts a string into a 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}`);
+    if (str.length !== Buffer32.SIZE * 2) {
+      throw new Error(`Expected string to be ${Buffer32.SIZE * 2} 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.
-   */
+  /** Converts a number into a 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.
-   */
+  /** Generates a random Buffer32. */
   public static random(): Buffer32 {
     return new Buffer32(Buffer.from(randomBytes(Buffer32.SIZE)));
   }

package/src/buffer/index.ts

@@ -1 +1,3 @@
 export * from './buffer32.js';
+export * from './buffer16.js';
+export * from './utils.js';

package/src/buffer/utils.ts

@@ -0,0 +1,8 @@
+/** Returns the number of bytes in the buffer, excluding any trailing zero bytes. */
+export function trimmedBytesLength(buf: Uint8Array): number {
+  let end = buf.length;
+  while (end > 0 && buf[end - 1] === 0) {
+    end--;
+  }
+  return end;
+}

package/src/collection/array.ts

@@ -89,6 +89,17 @@ export async function timesAsync<T>(n: number, fn: (i: number) => Promise<T>): P
   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.
@@ -127,6 +138,26 @@ 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.
@@ -157,7 +188,7 @@ export function areArraysEqual<T>(a: T[], b: T[], eq: (a: T, b: T) => boolean =
  * @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 {
+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]);
 }
 
@@ -167,13 +198,25 @@ export function sum(arr: number[]): number {
 }
 
 /** Computes the median of a numeric array. Returns undefined if array is empty. */
-export function median(arr: number[]) {
+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;
   }
-  const sorted = [...arr].sort((a, b) => a - b);
+
+  // 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]) / 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. */
@@ -201,3 +244,108 @@ export function stdDev(values: number[]) {
   }
   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

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