@aztec/foundation 0.0.0-test.0

package/src/serialize/free_funcs.ts

@@ -0,0 +1,204 @@
+import { Fr } from '../fields/fields.js';
+import type { Tuple } from './types.js';
+
+/**
+ * Convert a boolean value to its corresponding byte representation in a Buffer of size 1.
+ * The function takes a boolean value and writes it into a new buffer as either 1 (true) or 0 (false).
+ * This method is useful for converting a boolean value into a binary format that can be stored or transmitted easily.
+ *
+ * @param b - The boolean value to be converted.
+ * @returns A Buffer containing the byte representation of the input boolean value.
+ */
+export function boolToByte(b: boolean) {
+  const buf = Buffer.alloc(1);
+  buf.writeUInt8(b ? 1 : 0);
+  return buf;
+}
+
+/**
+ * @param n - The input number to be converted to a big-endian unsigned 16-bit integer Buffer.
+ * @param bufferSize - Optional, the size of the output Buffer (default is 2).
+ * @returns A Buffer containing the big-endian unsigned 16-bit integer representation of the input number.
+ */
+export function numToUInt16BE(n: number, bufferSize = 2) {
+  const buf = Buffer.alloc(bufferSize);
+  buf.writeUInt16BE(n, bufferSize - 2);
+  return buf;
+}
+
+/**
+ * Convert a number into a 4-byte little-endian unsigned integer buffer.
+ * The input number is serialized as an unsigned 32-bit integer in little-endian byte order,
+ * and returned as a Buffer of specified size (defaults to 4).
+ * If the provided bufferSize is greater than 4, the additional bytes will be padded with zeros.
+ *
+ * @param n - The number to be converted into a little-endian unsigned integer buffer.
+ * @param bufferSize - Optional, the size of the output buffer (default value is 4).
+ * @returns A Buffer containing the serialized little-endian unsigned integer representation of the input number.
+ */
+export function numToUInt32LE(n: number, bufferSize = 4) {
+  const buf = Buffer.alloc(bufferSize);
+  buf.writeUInt32LE(n, bufferSize - 4);
+  return buf;
+}
+
+/**
+ * Convert a number to a big-endian unsigned 32-bit integer Buffer.
+ * This function takes a number and an optional buffer size as input and creates a Buffer with the specified size (defaults to 4) containing the big-endian representation of the input number as an unsigned 32-bit integer. Note that the bufferSize should be greater than or equal to 4, otherwise the output Buffer might truncate the serialized value.
+ *
+ * @param n - The input number to be converted to a big-endian unsigned 32-bit integer Buffer.
+ * @param bufferSize - Optional, the size of the output Buffer (default is 4).
+ * @returns A Buffer containing the big-endian unsigned 32-bit integer representation of the input number.
+ */
+export function numToUInt32BE(n: number, bufferSize = 4) {
+  const buf = Buffer.alloc(bufferSize);
+  buf.writeUInt32BE(n, bufferSize - 4);
+  return buf;
+}
+
+/**
+ * Serialize a number into a big-endian signed 32-bit integer Buffer with the specified buffer size.
+ * This function converts the input number into its binary representation and stores it in a Buffer
+ * with the provided buffer size. By default, the buffer size is set to 4 bytes which represents a 32-bit integer.
+ * The function will use the last 4 bytes of the buffer to store the serialized number. If the input number
+ * is outside the range of a 32-bit signed integer, the resulting serialization may be incorrect due to truncation.
+ *
+ * @param n - The number to be serialized as a signed 32-bit integer.
+ * @param bufferSize - Optional, the size of the output Buffer (default is 4 bytes).
+ * @returns A Buffer containing the serialized big-endian signed 32-bit integer.
+ */
+export function numToInt32BE(n: number, bufferSize = 4) {
+  const buf = Buffer.alloc(bufferSize);
+  buf.writeInt32BE(n, bufferSize - 4);
+  return buf;
+}
+
+/**
+ * Convert a number to an 8-bit unsigned integer and return it as a Buffer of length 1.
+ * The input number is written as an 8-bit unsigned integer into the buffer. This function
+ * is useful for converting small numeric values to a standardized binary format that can be
+ * easily stored or transmitted.
+ *
+ * @param n - The number to be converted to an 8-bit unsigned integer.
+ * @returns A Buffer containing the 8-bit unsigned integer representation of the input number.
+ */
+export function numToUInt8(n: number) {
+  const bufferSize = 1;
+  const buf = Buffer.alloc(bufferSize);
+  buf.writeUInt8(n, 0);
+  return buf;
+}
+
+/**
+ * Adds a 4-byte byte-length prefix to a buffer.
+ * @param buf - The input Buffer to be prefixed
+ * @returns A Buffer with 4-byte byte-length prefix.
+ */
+export function prefixBufferWithLength(buf: Buffer) {
+  const lengthBuf = Buffer.alloc(4);
+  lengthBuf.writeUInt32BE(buf.length, 0);
+  return Buffer.concat([lengthBuf, buf]);
+}
+
+/**
+ * Parse a buffer as a big integer.
+ */
+export function toBigInt(buf: Buffer): bigint {
+  const hex = buf.toString('hex');
+  if (hex.length === 0) {
+    return BigInt(0);
+  }
+  return BigInt(`0x${hex}`);
+}
+
+/**
+ * Stores full 256 bits of information in 2 fields.
+ * @param buf - 32 bytes of data
+ * @returns 2 field elements
+ */
+export function to2Fields(buf: Buffer): [Fr, Fr] {
+  if (buf.length !== 32) {
+    throw new Error('Buffer must be 32 bytes');
+  }
+
+  // Split the hash into two fields, a high and a low
+  const buf1 = Buffer.concat([Buffer.alloc(16), buf.subarray(0, 16)]);
+  const buf2 = Buffer.concat([Buffer.alloc(16), buf.subarray(16, 32)]);
+
+  return [Fr.fromBuffer(buf1), Fr.fromBuffer(buf2)];
+}
+
+/**
+ * Reconstructs the original 32 bytes of data from 2 field elements.
+ * @param field1 - First field element
+ * @param field2 - Second field element
+ * @returns 32 bytes of data as a Buffer
+ */
+export function from2Fields(field1: Fr, field2: Fr): Buffer {
+  // Convert the field elements back to buffers
+  const buf1 = field1.toBuffer();
+  const buf2 = field2.toBuffer();
+
+  // Remove the padding (first 16 bytes) from each buffer
+  const originalPart1 = buf1.subarray(Fr.SIZE_IN_BYTES / 2, Fr.SIZE_IN_BYTES);
+  const originalPart2 = buf2.subarray(Fr.SIZE_IN_BYTES / 2, Fr.SIZE_IN_BYTES);
+
+  // Concatenate the two parts to form the original buffer
+  return Buffer.concat([originalPart1, originalPart2]);
+}
+
+/**
+ * Truncates SHA hashes to match Noir's truncated version
+ * @param buf - 32 bytes of data
+ * @returns 31 bytes of data padded to 32
+ */
+export function truncateAndPad(buf: Buffer): Buffer {
+  // Note that we always truncate here, to match solidity's sha256ToField()
+  if (buf.length !== 32) {
+    throw new Error('Buffer to truncate must be 32 bytes');
+  }
+  return Buffer.concat([Buffer.alloc(1), buf.subarray(0, 31)]);
+}
+
+/**
+ * Stores 248 bits of information in 1 field.
+ * @param buf - 32 or 31 bytes of data
+ * @returns 1 field element
+ */
+export function toTruncField(buf: Buffer): Fr {
+  if (buf.length !== 32 && buf.length !== 31) {
+    throw new Error('Buffer must be 31 or 32 bytes');
+  }
+  if ((buf.length == 32 && buf[0] == 0) || buf.length == 31) {
+    return Fr.fromBuffer(buf);
+  } else {
+    // Note: safer to NOT truncate here, all inputs are expected to be truncated
+    // from Noir or L1 Contracts or Class.hash() methods
+    throw new Error(`Number ${toBigInt(buf)} does not fit in 31 byte truncated buffer`);
+  }
+}
+
+/**
+ * Reconstructs the original 31 bytes of data from 1 truncated field element.
+ * @param field - field element
+ * @returns 31 bytes of data as a Buffer
+ */
+export function fromTruncField(field: Fr): Buffer {
+  const buffer = field.toBuffer();
+  if (buffer[0] != 0) {
+    throw new Error(`Number ${field} does not fit in 31 byte truncated buffer`);
+  }
+  return buffer;
+}
+
+export function fromFieldsTuple(fields: Tuple<Fr, 2>): Buffer {
+  return from2Fields(fields[0], fields[1]);
+}
+
+export function toHumanReadable(buf: Buffer, maxLen?: number): string {
+  const result = buf.every(byte => byte >= 32 && byte <= 126) ? buf.toString('ascii') : `0x${buf.toString('hex')}`;
+  if (maxLen && result.length > maxLen) {
+    return result.slice(0, maxLen) + '...';
+  }
+  return result;
+}

package/src/serialize/index.ts

@@ -0,0 +1,6 @@
+export * from './free_funcs.js';
+export * from './buffer_reader.js';
+export * from './field_reader.js';
+export * from './types.js';
+export * from './serialize.js';
+export * from './type_registry.js';

package/src/serialize/serialize.ts

@@ -0,0 +1,336 @@
+import { toBigIntBE, toBufferBE } from '../bigint-buffer/index.js';
+import { Fr } from '../fields/fields.js';
+import { numToUInt32BE } from './free_funcs.js';
+
+/**
+ * For serializing an array of fixed length buffers.
+ * @param arr - Array of bufferable.
+ * @param prefixLength - The length of the prefix (denominated in bytes).
+ * @returns The serialized buffers.
+ */
+export function serializeArrayOfBufferableToVector(objs: Bufferable[], prefixLength = 4): Buffer {
+  const arr = serializeToBufferArray(objs);
+  let lengthBuf: Buffer;
+  if (prefixLength === 1) {
+    lengthBuf = Buffer.alloc(1);
+    lengthBuf.writeUInt8(arr.length, 0);
+  } else if (prefixLength === 4) {
+    lengthBuf = Buffer.alloc(4);
+    lengthBuf.writeUInt32BE(arr.length, 0);
+  } else {
+    throw new Error(`Unsupported prefix length. Got ${prefixLength}, expected 1 or 4`);
+  }
+  return Buffer.concat([lengthBuf, ...arr]);
+}
+
+/**
+ * Helper function for deserializeArrayFromVector.
+ */
+type DeserializeFn<T> = (
+  buf: Buffer,
+  offset: number,
+) => {
+  /**
+   * The deserialized type.
+   */
+  elem: T;
+  /**
+   * How many bytes to advance by.
+   */
+  adv: number;
+};
+
+/**
+ * Deserializes an array from a vector on an element-by-element basis.
+ * @param deserialize - A function used to deserialize each element of the vector.
+ * @param vector - The vector to deserialize.
+ * @param offset - The position in the vector to start deserializing from.
+ * @returns Deserialized array and how many bytes we advanced by.
+ */
+export function deserializeArrayFromVector<T>(
+  deserialize: DeserializeFn<T>,
+  vector: Buffer,
+  offset = 0,
+): {
+  /**
+   * The deserialized array.
+   */
+  elem: T[];
+  /**
+   * How many bytes we advanced by.
+   */
+  adv: number;
+} {
+  let pos = offset;
+  const size = vector.readUInt32BE(pos);
+  pos += 4;
+  const arr = new Array<T>(size);
+  for (let i = 0; i < size; ++i) {
+    const { elem, adv } = deserialize(vector, pos);
+    pos += adv;
+    arr[i] = elem;
+  }
+  return { elem: arr, adv: pos - offset };
+}
+
+/**
+ * Cast a uint8 array to a number.
+ * @param array - The uint8 array.
+ * @returns The number.
+ */
+export function uint8ArrayToNum(array: Uint8Array): number {
+  const buf = Buffer.from(array);
+  return buf.readUint32LE();
+}
+
+/**
+ * Serializes a boolean to a buffer.
+ * @param value - Value to serialize.
+ * @returns The serialized boolean.
+ */
+export function boolToBuffer(value: boolean, bufferSize = 1): Buffer {
+  const buf = Buffer.alloc(bufferSize);
+  buf.writeUInt8(value ? 1 : 0, bufferSize - 1);
+  return buf;
+}
+
+/**
+ * Deserialize the 256-bit number at address `offset`.
+ * @param buf - The buffer.
+ * @param offset - The address.
+ * @returns The deserialized 256-bit field.
+ */
+export function deserializeField(buf: Buffer, offset = 0) {
+  const adv = 32;
+  return { elem: buf.slice(offset, offset + adv), adv };
+}
+
+/** A type that can be written to a buffer. */
+export type Bufferable =
+  | boolean
+  | Buffer
+  | Uint8Array
+  | number
+  | bigint
+  | string
+  | {
+      /**
+       * Serialize to a buffer.
+       */
+      toBuffer: () => Buffer;
+    }
+  | Bufferable[];
+
+/** A type that can be converted to a Field or a Field array. */
+export type Fieldable =
+  | Fr
+  | boolean
+  | number
+  | bigint
+  | Buffer
+  | {
+      /**
+       * Serialize to a field.
+       * @dev Duplicate to `toField` but left as is as it is used in AVM codebase.
+       */
+      toFr: () => Fr;
+    }
+  | {
+      /** Serialize to a field. */
+      toField: () => Fr;
+    }
+  | {
+      /** Serialize to an array of fields. */
+      toFields: () => Fr[];
+    }
+  | Fieldable[];
+
+/**
+ * Serializes a list of objects contiguously.
+ * @param objs - Objects to serialize.
+ * @returns A buffer list with the concatenation of all fields.
+ */
+export function serializeToBufferArray(...objs: Bufferable[]): Buffer[] {
+  const ret: Buffer[] = [];
+  for (const obj of objs) {
+    if (Array.isArray(obj)) {
+      ret.push(...serializeToBufferArray(...obj));
+    } else if (Buffer.isBuffer(obj)) {
+      ret.push(obj);
+    } else if (typeof obj === 'boolean') {
+      ret.push(boolToBuffer(obj));
+    } else if (typeof obj === 'bigint') {
+      // Throw if bigint does not fit into 32 bytes
+      if (obj > BigInt('0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff')) {
+        throw new Error(`BigInt ${obj} does not fit into 32 bytes`);
+      }
+      ret.push(serializeBigInt(obj));
+    } else if (typeof obj === 'number') {
+      // Note: barretenberg assumes everything is big-endian
+      ret.push(numToUInt32BE(obj)); // TODO: Are we always passing numbers as UInt32?
+    } else if (typeof obj === 'string') {
+      ret.push(numToUInt32BE(obj.length));
+      ret.push(Buffer.from(obj));
+    } else if ('toBuffer' in obj) {
+      ret.push(obj.toBuffer());
+    } else {
+      throw new Error(`Cannot serialize input to buffer: ${typeof obj} ${(obj as any).constructor?.name}`);
+    }
+  }
+  return ret;
+}
+
+/**
+ * Serializes a list of objects contiguously.
+ * @param objs - Objects to serialize.
+ * @returns An array of fields with the concatenation of all fields.
+ */
+export function serializeToFields(...objs: Fieldable[]): Fr[] {
+  const ret: Fr[] = [];
+  for (const obj of objs) {
+    if (Array.isArray(obj)) {
+      ret.push(...serializeToFields(...obj));
+    } else if (obj instanceof Fr) {
+      ret.push(obj);
+    } else if (typeof obj === 'boolean' || typeof obj === 'number' || typeof obj === 'bigint') {
+      ret.push(new Fr(obj));
+    } else if ('toFields' in obj) {
+      ret.push(...obj.toFields());
+    } else if ('toFr' in obj) {
+      ret.push(obj.toFr());
+    } else if ('toField' in obj) {
+      ret.push(obj.toField());
+    } else if (Buffer.isBuffer(obj)) {
+      ret.push(Fr.fromBuffer(obj));
+    } else {
+      throw new Error(`Cannot serialize input to field: ${typeof obj} ${(obj as any).constructor?.name}`);
+    }
+  }
+  return ret;
+}
+
+/**
+ * Serializes a list of objects contiguously.
+ * @param objs - Objects to serialize.
+ * @returns A single buffer with the concatenation of all fields.
+ */
+export function serializeToBuffer(...objs: Bufferable[]): Buffer {
+  return Buffer.concat(serializeToBufferArray(...objs));
+}
+
+/**
+ * Returns a user-friendly JSON representation of an object, showing buffers as hex strings.
+ * @param obj - Object to json-stringify.
+ * @returns A JSON string.
+ */
+export function toFriendlyJSON(obj: object): string {
+  return JSON.stringify(
+    obj,
+    (key, value) => {
+      if (value !== null && typeof value === 'object' && value.type === 'Buffer' && Array.isArray(value.data)) {
+        return '0x' + Buffer.from(value.data).toString('hex');
+      } else if (typeof value === 'bigint') {
+        return value.toString();
+      } else if (
+        value &&
+        (
+          value as {
+            /**
+             * Signature of the target serialization function.
+             */
+            toFriendlyJSON: () => string;
+          }
+        ).toFriendlyJSON
+      ) {
+        return value.toFriendlyJSON();
+      } else if (value && value.type && ['Fr', 'Fq', 'AztecAddress', 'EthAddress'].includes(value.type)) {
+        return value.value;
+      } else {
+        return value;
+      }
+    },
+    2,
+  );
+}
+
+/**
+ * Serialize a BigInt value into a Buffer of specified width.
+ * The function converts the input BigInt into its big-endian representation and stores it in a Buffer of the given width.
+ * If the width is not provided, a default value of 32 bytes will be used. It is important to provide an appropriate width
+ * to avoid truncation or incorrect serialization of large BigInt values.
+ *
+ * @param n - The BigInt value to be serialized.
+ * @param width - The width (in bytes) of the output Buffer, optional with default value 32.
+ * @returns A Buffer containing the serialized BigInt value in big-endian format.
+ */
+export function serializeBigInt(n: bigint, width = 32) {
+  return toBufferBE(n, width);
+}
+
+/**
+ * Deserialize a big integer from a buffer, given an offset and width.
+ * Reads the specified number of bytes from the buffer starting at the offset, converts it to a big integer, and returns the deserialized result along with the number of bytes read (advanced).
+ *
+ * @param buf - The buffer containing the big integer to be deserialized.
+ * @param offset - The position in the buffer where the big integer starts. Defaults to 0.
+ * @param width - The number of bytes to read from the buffer for the big integer. Defaults to 32.
+ * @returns An object containing the deserialized big integer value ('elem') and the number of bytes advanced ('adv').
+ */
+export function deserializeBigInt(buf: Buffer, offset = 0, width = 32) {
+  return { elem: toBigIntBE(buf.subarray(offset, offset + width)), adv: width };
+}
+
+/**
+ * Serializes a Date object into a Buffer containing its timestamp as a big integer value.
+ * The resulting Buffer has a fixed width of 8 bytes, representing a 64-bit big-endian integer.
+ * This function is useful for converting date values into a binary format that can be stored or transmitted easily.
+ *
+ * @param date - The Date object to be serialized.
+ * @returns A Buffer containing the serialized timestamp of the input Date object.
+ */
+export function serializeDate(date: Date) {
+  return serializeBigInt(BigInt(date.getTime()), 8);
+}
+
+/**
+ * Deserialize a boolean value from a given buffer at the specified offset.
+ * Reads a single byte at the provided offset in the buffer and returns
+ * the deserialized boolean value along with the number of bytes read (adv).
+ *
+ * @param buf - The buffer containing the serialized boolean value.
+ * @param offset - The position in the buffer to start reading the boolean value.
+ * @returns An object containing the deserialized boolean value (elem) and the number of bytes read (adv).
+ */
+export function deserializeBool(buf: Buffer, offset = 0) {
+  const adv = 1;
+  return { elem: buf.readUInt8(offset), adv };
+}
+
+/**
+ * Deserialize a 4-byte unsigned integer from a buffer, starting at the specified offset.
+ * The deserialization reads 4 bytes from the given buffer and converts it into a number.
+ * Returns an object containing the deserialized unsigned integer and the number of bytes advanced (4).
+ *
+ * @param buf - The buffer containing the serialized unsigned integer.
+ * @param offset - The starting position in the buffer to deserialize from (default is 0).
+ * @returns An object with the deserialized unsigned integer as 'elem' and the number of bytes advanced ('adv') as 4.
+ */
+export function deserializeUInt32(buf: Buffer, offset = 0) {
+  const adv = 4;
+  return { elem: buf.readUInt32BE(offset), adv };
+}
+
+/**
+ * Deserialize a signed 32-bit integer from a buffer at the given offset.
+ * The input 'buf' should be a Buffer containing binary data, and 'offset' should be the position in the buffer
+ * where the signed 32-bit integer starts. Returns an object with both the deserialized integer (elem) and the
+ * number of bytes advanced in the buffer (adv, always equal to 4).
+ *
+ * @param buf - The buffer containing the binary data.
+ * @param offset - Optional, the position in the buffer where the signed 32-bit integer starts (default is 0).
+ * @returns An object with the deserialized integer as 'elem' and the number of bytes advanced as 'adv'.
+ */
+export function deserializeInt32(buf: Buffer, offset = 0) {
+  const adv = 4;
+  return { elem: buf.readInt32BE(offset), adv };
+}

package/src/serialize/type_registry.ts

@@ -0,0 +1,75 @@
+import { mapValues } from '../collection/object.js';
+
+type Deserializable = { fromString(str: string): object };
+
+/**
+ * Register a class here that has a toJSON method that returns:
+ * ```
+ * {
+ *   "type": "ExampleClassName",
+ *   "value": <result of ExampleClassName.toString()>
+ * }
+ * ```
+ * and has an e.g. ExampleClassName.fromString(string) method.
+ * This means you can then easily serialize/deserialize the type using JSON.stringify and JSON.parse.
+ */
+export class TypeRegistry {
+  private static registry: Map<string, Deserializable> = new Map();
+
+  public static register(typeName: string, constructor: Deserializable): void {
+    this.registry.set(typeName, constructor);
+  }
+
+  public static getConstructor(typeName: string): Deserializable | undefined {
+    return this.registry.get(typeName);
+  }
+}
+
+function replace<T>(value: T) {
+  if (
+    value &&
+    typeof value === 'object' &&
+    'toString' in value &&
+    TypeRegistry.getConstructor(value.constructor.name)
+  ) {
+    return {
+      type: value.constructor.name,
+      value: value.toString(),
+    };
+  }
+
+  return value;
+}
+
+// Resolver function that enables JSON serialization of BigInts.
+export function resolver(_: any, value: any) {
+  if (typeof value === 'bigint') {
+    return value.toString() + 'n';
+  }
+
+  if (typeof value === 'object' && value) {
+    if (Array.isArray(value)) {
+      return value.map(replace);
+    } else if (Buffer.isBuffer(value)) {
+      return { type: 'buffer', value: value.toString('hex') };
+    } else {
+      return mapValues(value, replace);
+    }
+  }
+
+  return value;
+}
+
+// Reviver function that uses TypeRegistry to instantiate objects.
+export function reviver(key: string, value: any) {
+  if (typeof value === 'string' && /^\d+n$/.test(value)) {
+    return BigInt(value.slice(0, -1));
+  }
+  if (value && typeof value === 'object' && 'type' in value && 'value' in value) {
+    const Constructor = TypeRegistry.getConstructor(value.type);
+    if (Constructor) {
+      return Constructor.fromString(value.value);
+    }
+  }
+  return value;
+}

package/src/serialize/types.ts

@@ -0,0 +1,40 @@
+/**
+ * Represents a fixed-length array.
+ */
+export type Tuple<T, N extends number> = N extends N ? (number extends N ? T[] : _Tuple<T, N, []>) : never;
+/**
+ * Recursive type helper for constructing a fixed-length tuple of a given type.
+ * This is utilized internally by Tuple to create the final fixed-length tuple.
+ */
+type _Tuple<T, N extends number, R extends unknown[]> = R['length'] extends N ? R : _Tuple<T, N, [T, ...R]>;
+
+/**
+ * Check an array size, and cast it to a tuple.
+ * @param array - The array.
+ * @param n - The size.
+ * @returns The case tuple, or throws Error.
+ */
+export function assertLength<T, N extends number>(array: T[], n: N): Tuple<T, N> {
+  if (array.length !== n) {
+    throw new Error(`Wrong 'fixed array' size. Expected ${n}, got ${array.length}.`);
+  }
+  return array as Tuple<T, N>;
+}
+/**
+ * Annoying, mapping a tuple does not preserve length.
+ * This is a helper to preserve length during a map operation.
+ * @typeparam T - The original array type.
+ */
+type MapTuple<T extends any[], F extends (item: any) => any> = {
+  [K in keyof T]: T[K] extends infer U ? (F extends (item: U) => infer V ? V : never) : never;
+};
+
+/**
+ * Annoyingly, mapping a tuple does not preserve length.
+ * This is a helper to preserve length during a map operation.
+ * @see https://github.com/microsoft/TypeScript/issues/29841.
+ * @param array - A tuple array.
+ */
+export function mapTuple<T extends any[], F extends (item: T[number]) => any>(tuple: T, fn: F): MapTuple<T, F> {
+  return tuple.map(fn) as MapTuple<T, F>;
+}