@aztec/foundation 0.1.0-alpha10

package/src/timer/timeout.ts

@@ -0,0 +1,64 @@
+/**
+ * TimeoutTask class creates an instance for managing and executing a given asynchronous function with a specified timeout duration.
+ * The task will be automatically interrupted if it exceeds the given timeout duration, and will throw a custom error message.
+ * Additional information such as execution time can be retrieved using getTime method after the task has been executed.
+ *
+ * @typeparam T - The return type of the asynchronous function to be executed.
+ */
+export class TimeoutTask<T> {
+  private interruptPromise!: Promise<any>;
+  private interrupt = () => {};
+  private totalTime = 0;
+
+  constructor(private fn: () => Promise<T>, private timeout = 0, fnName = '') {
+    this.interruptPromise = new Promise<T>((_, reject) => {
+      this.interrupt = () => reject(new Error(`Timeout${fnName ? ` running ${fnName}` : ''} after ${timeout}ms.`));
+    });
+  }
+
+  /**
+   * Executes the given function with a specified timeout.
+   * If the function takes longer than the timeout, it will be interrupted and an error will be thrown.
+   * The total execution time of the function will be stored in the totalTime property.
+   *
+   * @returns The result of the executed function if completed within the timeout.
+   * @throws An error with a message indicating the function was interrupted due to exceeding the specified timeout.
+   */
+  public async exec() {
+    const interruptTimeout = !this.timeout ? 0 : setTimeout(this.interrupt, this.timeout);
+    try {
+      const start = Date.now();
+      const result = await Promise.race<T>([this.fn(), this.interruptPromise]);
+      this.totalTime = Date.now() - start;
+      return result;
+    } finally {
+      clearTimeout(interruptTimeout);
+    }
+  }
+
+  /**
+   * Returns the interrupt promise associated with the TimeoutTask instance.
+   * The interrupt promise is used internally to reject the task when a timeout occurs.
+   * This method can be helpful when debugging or tracking the state of the task.
+   *
+   * @returns The interrupt promise associated with the task.
+   */
+  public getInterruptPromise() {
+    return this.interruptPromise;
+  }
+
+  /**
+   * Get the total time spent on the most recent execution of the wrapped function.
+   * This method provides the duration from the start to the end of the function execution, whether it completed or timed out.
+   *
+   * @returns The total time in milliseconds spent on the most recent function execution.
+   */
+  public getTime() {
+    return this.totalTime;
+  }
+}
+
+export const executeTimeout = async <T>(fn: () => Promise<T>, timeout = 0, fnName = '') => {
+  const task = new TimeoutTask(fn, timeout, fnName);
+  return await task.exec();
+};

package/src/timer/timer.ts

@@ -0,0 +1,41 @@
+/**
+ * Timer class to measure time intervals in milliseconds and seconds.
+ * Upon instantiation, it stores the current timestamp as the starting point.
+ * The 'ms()' method returns the elapsed time in milliseconds,
+ * while the 's()' method returns the elapsed time in seconds.
+ *
+ * @example
+ * const timer = new Timer();
+ * setTimeout(() =\> \{
+ *   console.log(`Elapsed time: ${timer.ms()} ms`);
+ * \}, 1000);
+ */
+export class Timer {
+  private start: number;
+
+  constructor() {
+    this.start = new Date().getTime();
+  }
+
+  /**
+   * Returns the elapsed time in milliseconds since the Timer instance was created.
+   * Provides a simple and convenient way to measure the time duration between two events
+   * or monitor performance of specific code sections.
+   *
+   * @returns The elapsed time in milliseconds.
+   */
+  public ms() {
+    return new Date().getTime() - this.start;
+  }
+
+  /**
+   * Returns the time elapsed since the Timer instance was created, in seconds.
+   * The value is calculated by subtracting the initial start time from the current time
+   * and dividing the result by 1000 to convert milliseconds to seconds.
+   *
+   * @returns The elapsed time in seconds.
+   */
+  public s() {
+    return (new Date().getTime() - this.start) / 1000;
+  }
+}

package/src/transport/browser/index.ts

@@ -0,0 +1,4 @@
+export * from './worker_connector.js';
+export * from './worker_listener.js';
+export * from './shared_worker_connector.js';
+export * from './shared_worker_listener.js';

package/src/transport/browser/message_port_socket.ts

@@ -0,0 +1,48 @@
+import { Socket } from '../interface/socket.js';
+
+/**
+ * An implementation of a TransportSocket using MessagePorts.
+ */
+export class MessagePortSocket implements Socket {
+  constructor(private port: MessagePort) {}
+
+  /**
+   * Send a message to the connected MessagePort, optionally transferring ownership of certain objects.
+   * The 'msg' parameter can be any structured data type and will be sent to the other end of the MessagePort.
+   * The optional 'transfer' parameter is an array of Transferable objects whose ownership will be transferred,
+   * making them inaccessible on the sending side. This can improve performance for large data transfers.
+   *
+   * @param msg - The message to be sent through the MessagePort.
+   * @param transfer - An optional array of Transferable objects to transfer ownership.
+   * @returns A Promise that resolves when the message has been sent.
+   */
+  send(msg: any, transfer: Transferable[] = []): Promise<void> {
+    this.port.postMessage(msg, transfer);
+    return Promise.resolve();
+  }
+
+  /**
+   * Register a callback function to handle incoming messages from the MessagePort.
+   * The provided callback will be invoked with the message data whenever a new message arrives.
+   * Note that only one callback can be registered at a time. Subsequent calls to this method
+   * will overwrite the previously registered callback.
+   *
+   * @param cb - The callback function to handle incoming messages.
+   */
+  registerHandler(cb: (msg: any) => any): void {
+    this.port.onmessage = event => cb(event.data);
+  }
+
+  /**
+   * Close the MessagePort, unregister the message handler, and send an undefined message.
+   * The 'close' function is useful for gracefully shutting down a connection between two
+   * endpoints by sending an undefined message as an indication of disconnection before
+   * closing the port. After calling this method, the MessagePortSocket instance should not
+   * be used again.
+   */
+  close() {
+    void this.send(undefined);
+    this.port.onmessage = null;
+    this.port.close();
+  }
+}

package/src/transport/browser/shared_worker_connector.ts

@@ -0,0 +1,21 @@
+import { Connector } from '../interface/connector.js';
+import { MessagePortSocket } from './message_port_socket.js';
+
+/**
+ * SharedWorkerConnector is an implementation of the Connector interface, specifically for SharedWorkers.
+ * It enables the creation of MessagePortSockets that communicate with a shared worker and allow
+ * multiple scripts to communicate with the worker using the same connection.
+ */
+export class SharedWorkerConnector implements Connector {
+  constructor(private worker: SharedWorker) {}
+
+  /**
+   * Creates a new MessagePortSocket instance using the SharedWorker's port.
+   * This method allows for easy creation of sockets to communicate with the SharedWorker.
+   *
+   * @returns A Promise that resolves to a new MessagePortSocket instance.
+   */
+  createSocket() {
+    return Promise.resolve(new MessagePortSocket(this.worker.port));
+  }
+}

package/src/transport/browser/shared_worker_listener.ts

@@ -0,0 +1,52 @@
+import EventEmitter from 'events';
+import { Listener } from '../interface/listener.js';
+import { MessagePortSocket } from './message_port_socket.js';
+
+/**
+ * Represents the global scope of a Shared Worker.
+ * Provides functionality to handle incoming connections and manage communication with other scripts
+ * running in a shared context, enabling concurrent access and efficient resource sharing among those scripts.
+ */
+declare interface SharedWorkerGlobalScope {
+  /**
+   * Event handler for new connections to the Shared Worker.
+   */
+  onconnect: (...args: any) => any;
+}
+
+/**
+ * SharedWorkerListener is an extension of the EventEmitter class that implements the Listener interface.
+ * It provides functionality to handle incoming messages from a shared worker and emit events for new sockets
+ * created in response to these incoming connections. This class is meant to be used in the context of managing
+ * MessagePort connections within the SharedWorkerGlobalScope.
+ */
+export class SharedWorkerListener extends EventEmitter implements Listener {
+  constructor(private worker: SharedWorkerGlobalScope) {
+    super();
+  }
+
+  /**
+   * Initializes the shared worker listener by assigning the 'handleMessageEvent' method as the event handler
+   * for the 'onconnect' event of the SharedWorkerGlobalScope. The 'handleMessageEvent' function will be called
+   * whenever a new connection is established with the shared worker.
+   */
+  open() {
+    this.worker.onconnect = this.handleMessageEvent;
+  }
+
+  /**
+   * Closes the SharedWorkerListener by detaching the 'onconnect' event handler.
+   * This stops the listener from emitting new sockets on incoming connections.
+   */
+  close() {
+    this.worker.onconnect = () => {};
+  }
+
+  private handleMessageEvent = (event: MessageEvent) => {
+    const [port] = event.ports;
+    if (!port) {
+      return;
+    }
+    this.emit('new_socket', new MessagePortSocket(port));
+  };
+}

package/src/transport/browser/worker_connector.ts

@@ -0,0 +1,30 @@
+import { Connector } from '../interface/connector.js';
+import { MessagePortSocket } from './message_port_socket.js';
+
+/**
+ * WorkerConnector is a class implementing the Connector interface for creating communication sockets
+ * with Web Workers. It allows to establish a connection with the worker and create MessagePortSockets
+ * using MessageChannels, enabling seamless communication between the main thread and worker threads.
+ *
+ * @example
+ * const worker = new Worker('./myWorker.js');
+ * const connector = new WorkerConnector(worker);
+ * const socket = await connector.createSocket();
+ * socket.send('Hello, worker!');
+ */
+export class WorkerConnector implements Connector {
+  constructor(private worker: Worker) {}
+
+  /**
+   * Creates a new MessagePortSocket instance by establishing a connection between the Worker and the main thread.
+   * A MessageChannel is created, and one of its ports is sent to the Worker using postMessage.
+   * The other port is used to create a new MessagePortSocket which is then returned as a Promise.
+   *
+   * @returns A Promise that resolves to a new MessagePortSocket instance.
+   */
+  createSocket() {
+    const channel = new MessageChannel();
+    this.worker.postMessage('', [channel.port2]);
+    return Promise.resolve(new MessagePortSocket(channel.port1));
+  }
+}

package/src/transport/browser/worker_listener.ts

@@ -0,0 +1,53 @@
+import EventEmitter from 'events';
+import { Listener } from '../interface/listener.js';
+import { MessagePortSocket } from './message_port_socket.js';
+
+/**
+ * Represents a DedicatedWorkerGlobalScope, which is the global execution context for a dedicated worker.
+ * Provides properties and methods to manage the worker's lifecycle and communication with other threads or workers.
+ */
+declare interface DedicatedWorkerGlobalScope {
+  /**
+   * Handler for incoming messages from other threads or workers.
+   */
+  onmessage: any;
+}
+
+/**
+ * WorkerListener is a class that extends EventEmitter and implements the Listener interface.
+ * It listens for incoming connections on a dedicated worker global scope, and emits a 'new_socket' event
+ * with a MessagePortSocket instance for each new connection. This allows applications to communicate
+ * with other workers or main thread through the MessagePortSocket abstraction.
+ *
+ * The open() method starts listening for incoming connections, while the close() method stops it.
+ */
+export class WorkerListener extends EventEmitter implements Listener {
+  constructor(private worker: DedicatedWorkerGlobalScope) {
+    super();
+  }
+
+  /**
+   * Initializes the WorkerListener by setting the 'onmessage' event handler of the worker.
+   * The 'onmessage' event will be triggered when the worker receives a message, and it will then
+   * call the handleMessageEvent method to handle incoming connections.
+   */
+  open() {
+    this.worker.onmessage = this.handleMessageEvent;
+  }
+
+  /**
+   * Close the worker listener by removing the 'onmessage' event handler.
+   * This method effectively stops the WorkerListener from reacting to new incoming messages.
+   */
+  close() {
+    this.worker.onmessage = () => {};
+  }
+
+  private handleMessageEvent = (event: MessageEvent) => {
+    const [port] = event.ports;
+    if (!port) {
+      return;
+    }
+    this.emit('new_socket', new MessagePortSocket(port));
+  };
+}

package/src/transport/dispatch/create_dispatch_fn.ts

@@ -0,0 +1,33 @@
+import { createDebugLogger } from '../../log/debug.js';
+
+/**
+ * Represents a message object for dispatching function calls.
+ * Contains the function name ('fn') and an array of arguments ('args') required to call the target method.
+ */
+export interface DispatchMsg {
+  /**
+   * Name of the target method to be called.
+   */
+  fn: string;
+  /**
+   * An array of arguments to be passed to the target method.
+   */
+  args: any[];
+}
+
+/**
+ * Creates a dispatch function that calls the target's specified method with provided arguments.
+ * The created dispatch function takes a DispatchMsg object as input, which contains the name of
+ * the method to be called ('fn') and an array of arguments to be passed to the method ('args').
+ *
+ * @param targetFn - A function that returns the target object containing the methods to be dispatched.
+ * @param debug - Optional logging function for debugging purposes.
+ * @returns A dispatch function that accepts a DispatchMsg object and calls the target's method with provided arguments.
+ */
+export function createDispatchFn(targetFn: () => any, debug = createDebugLogger('aztec:foundation:dispatch')) {
+  return async ({ fn, args }: DispatchMsg) => {
+    const target = targetFn();
+    debug(`dispatching to ${target}: ${fn}`, args);
+    return await target[fn](...args);
+  };
+}

package/src/transport/dispatch/create_dispatch_proxy.ts

@@ -0,0 +1,140 @@
+import { DispatchMsg } from './create_dispatch_fn.js';
+import { TransportClient } from '../transport_client.js';
+import { EventEmitter } from 'events';
+import { isTransferDescriptor, TransferDescriptor } from '../interface/transferable.js';
+
+/**
+ * FilterOutAttributes type filters out all non-method properties of an object, leaving only the attributes
+ * that are functions. This is useful for creating proxies or wrappers around objects while focusing only
+ * on their methods and ignoring other properties.
+ */
+type FilterOutAttributes<Base> = {
+  [Key in keyof Base]: Base[Key] extends (...any: any) => any ? Base[Key] : never;
+};
+
+/**
+ * Takes a function type `F` and returns a new function type with the same input parameters as `F`,
+ * but returning a Promise of the original return type of `F`. This is useful for converting sync
+ * functions or functions that take callbacks into a version that returns a Promise.
+ */
+type PromisifyFunction<F extends (...any: any) => any> = (...args: Parameters<F>) => Promise<ReturnType<F>>;
+
+/**
+ * Transforms the provided object type by converting each of its function properties into their
+ * promise-returning counterparts. If a function property already returns a promise, it remains unchanged.
+ * This is useful when wrapping synchronous methods to return promises in order to standardize the API for
+ * asynchronous operations.
+ *
+ * @typeParam Base - The type of the object whose function properties need to be converted into their
+ *                   promise-returning versions.
+ */
+type Promisify<Base extends { [key: string]: (...any: any) => any }> = {
+  [Key in keyof Base]: ReturnType<Base[Key]> extends Promise<any> ? Base[Key] : PromisifyFunction<Base[Key]>;
+};
+
+/**
+ * Type that transforms a tuple of types, replacing each type 'T' with either 'T' or a `TransferDescriptor<T>` if 'T' is `Transferable`.
+ * This is useful for handling arguments of functions that may accept both original and transferable representations of objects.
+ */
+type TransferTypes<Tuple extends [...args: any]> = {
+  [Index in keyof Tuple]: Tuple[Index] | (Tuple[Index] extends Transferable ? TransferDescriptor<Tuple[Index]> : never);
+};
+
+/**
+ * Annoying.
+ * @see https://github.com/microsoft/TypeScript/issues/29919
+ * There's a bug that means we can't map over the tuple or function parameter types to make them transferrable, if
+ * we use the Parameters builtin, and then try to map.
+ * So instead we inline the Parameters builtin and apply the TransferTypes to the parameters within the inline.
+ * Once the above is fixed we could in theory just do:
+ *
+ * type MakeFunctionTransferrable\<TFunction extends (...args: any) =\> any\> = (
+ *   ...args: TransferTypes\<Parameters\<TFunction\>\>
+ * ) =\> ReturnType<TFunction>;
+ */
+type MakeFunctionTransferrable<TFunction extends (...args: any) => any> = (
+  ...args: TFunction extends (...args: infer P) => any ? TransferTypes<P> : never
+) => ReturnType<TFunction>;
+
+/**
+ * Transferrable type represents a utility type that maps over the provided Base object's methods,
+ * transforming their argument types to support transferable objects. This is useful when dealing
+ * with operations across different environments or threads, such as Web Workers or Node.js processes,
+ * where certain objects need to be transferred instead of being serialized and deserialized.
+ */
+type Transferrable<Base extends { [key: string]: (...any: any) => any }> = {
+  [Key in keyof Base]: MakeFunctionTransferrable<Base[Key]>;
+};
+
+/**
+ * Proxify is a mapped type that takes an object with functions as its properties and returns
+ * a new object with the same properties, but with each function transformed to return a Promise
+ * and accept Transferable types in place of their original parameters. This type is useful for
+ * creating proxies that communicate over different environments or threads while maintaining
+ * the original class's method signatures, allowing for type-safe interaction with remote instances.
+ */
+export type Proxify<T> = Promisify<Transferrable<FilterOutAttributes<T>>>;
+
+/**
+ * Creates a proxy object for the provided class, wrapping each method in a request function.
+ * The resulting proxy object allows invoking methods of the original class, but their execution
+ * is delegated to the request function. This is useful when executing methods across different
+ * environments or threads, such as Web Workers or Node.js processes.
+ *
+ * @typeParam T - The type of the class to create a proxy for.
+ * @param class_ - The class constructor to create a proxy for.
+ * @param requestFn - A higher-order function that takes a method name and returns a function
+ *                    with the same signature as the original method, which wraps the actual
+ *                    invocation in a custom logic (e.g., sending a message to another thread).
+ * @returns An object whose methods match those of the original class, but whose execution is
+ *          delegated to the provided request function.
+ */
+export function createDispatchProxyFromFn<T>(
+  class_: { new (...args: any[]): T },
+  requestFn: (fn: string) => (...args: any[]) => Promise<any>,
+): Proxify<T> {
+  const proxy: any = class_.prototype instanceof EventEmitter ? new EventEmitter() : {};
+  for (const fn of Object.getOwnPropertyNames(class_.prototype)) {
+    if (fn === 'constructor') {
+      continue;
+    }
+    proxy[fn] = requestFn(fn);
+  }
+  return proxy;
+}
+
+/**
+ * Creates a proxy for the given class that transparently dispatches method calls over a transport client.
+ * The proxy allows calling methods on remote instances of the class through the provided transport client
+ * while maintaining the correct return types and handling promises. If the class inherits from EventEmitter,
+ * it also handles event emissions through the transport client.
+ *
+ * @param class_ - The constructor function of the class to create the proxy for.
+ * @param transportClient - The TransportClient instance used to handle communication between proxies.
+ * @returns A proxified version of the given class with methods dispatched over the transport client.
+ */
+export function createDispatchProxy<T>(
+  class_: { new (...args: any[]): T },
+  transportClient: TransportClient<DispatchMsg>,
+): Proxify<T> {
+  // Create a proxy of class_ that passes along methods over our transportClient
+  const proxy = createDispatchProxyFromFn(class_, (fn: string) => (...args: any[]) => {
+    // Pass our proxied function name and arguments over our transport client
+    const transfer: Transferable[] = args.reduce(
+      (acc, a) => (isTransferDescriptor(a) ? [...acc, ...a.transferables] : acc),
+      [] as Transferable[],
+    );
+    args = args.map(a => (isTransferDescriptor(a) ? a.send : a));
+    return transportClient.request({ fn, args }, transfer);
+  });
+  if (proxy instanceof EventEmitter) {
+    // Handle proxied 'emit' calls if our proxy object is an EventEmitter
+    transportClient.on('event_msg', ({ fn, args }) => {
+      if (fn === 'emit') {
+        const [eventName, ...restArgs] = args;
+        proxy.emit(eventName, ...restArgs);
+      }
+    });
+  }
+  return proxy;
+}

package/src/transport/dispatch/messages.ts

@@ -0,0 +1,58 @@
+/**
+ * Represents a request message.
+ * Contains a unique identifier (msgId) and a payload object.
+ */
+export interface RequestMessage<Payload> {
+  /**
+   * A unique identifier for a message.
+   */
+  msgId: number;
+  /**
+   * The data content carried within a message.
+   */
+  payload: Payload;
+}
+
+/**
+ * Represents a structured response message.
+ * Contains an identifier to match with the corresponding request.
+ */
+export interface ResponseMessage<Payload> {
+  /**
+   * A unique identifier for the message.
+   */
+  msgId: number;
+  /**
+   * The data content carried within the message.
+   */
+  payload?: Payload;
+  /**
+   * An optional error description in case the response contains an error instead of a payload.
+   */
+  error?: string;
+}
+
+/**
+ * Represents an event-based message in a communication system.
+ * Contains a payload with the relevant data associated with a specific event occurrence.
+ */
+export interface EventMessage<Payload> {
+  /**
+   * The data content associated with a message.
+   */
+  payload: Payload;
+}
+
+/**
+ * Determines if the given 'msg' is an EventMessage by checking if its 'msgId' property is undefined.
+ * Returns true if the input message is of type EventMessage, otherwise false. This utility function can be used
+ * to differentiate between instances of ResponseMessage and EventMessage that share a common Payload type.
+ *
+ * @param msg - The message object that can be either a ResponseMessage or EventMessage with a specific payload.
+ * @returns A boolean value indicating whether the input message is an EventMessage (true) or not (false).
+ */
+export function isEventMessage<Payload>(
+  msg: ResponseMessage<Payload> | EventMessage<Payload>,
+): msg is EventMessage<Payload> {
+  return (msg as ResponseMessage<Payload>).msgId === undefined;
+}

package/src/transport/index.ts

@@ -0,0 +1,11 @@
+export * from './dispatch/create_dispatch_fn.js';
+export * from './dispatch/create_dispatch_proxy.js';
+export * from './dispatch/messages.js';
+export * from './interface/connector.js';
+export * from './interface/listener.js';
+export * from './interface/socket.js';
+export * from './interface/transferable.js';
+export * from './transport_client.js';
+export * from './transport_server.js';
+export * from './browser/index.js';
+export * from './node/index.js';

package/src/transport/interface/connector.ts

@@ -0,0 +1,8 @@
+import { Socket } from './socket.js';
+
+/**
+ * Opens a socket with corresponding TransportListener.
+ */
+export interface Connector {
+  createSocket(): Promise<Socket>;
+}

package/src/transport/interface/listener.ts

@@ -0,0 +1,14 @@
+import EventEmitter from 'events';
+import { Socket } from './socket.js';
+
+/**
+ * Once opened, an implementation of a TransportListener will emit `new_socket` events as new clients connect.
+ * Possible implementations could include MessageChannels or WebSockets.
+ */
+export interface Listener extends EventEmitter {
+  open(): void;
+
+  close(): void;
+
+  on(name: 'new_socket', cb: (client: Socket) => void): this;
+}

package/src/transport/interface/socket.ts

@@ -0,0 +1,12 @@
+/**
+ * Represents one end of a socket connection.
+ * A message sent via `send` will be handled by the corresponding Socket's handler function at the other end.
+ * Implementations could use e.g. MessagePorts for communication between browser workers,
+ * or WebSockets for communication between processes.
+ * If `registerHandler` callback receives `undefined` that signals the other end closed.
+ */
+export interface Socket {
+  send(msg: any, transfer?: Transferable[]): Promise<void>;
+  registerHandler(cb: (msg: any) => any): void;
+  close(): void;
+}