@aztec/foundation 0.16.3 → 0.16.5

package/src/transport/dispatch/create_dispatch_proxy.ts

@@ -1,141 +0,0 @@
-import { EventEmitter } from 'events';
-
-import { TransferDescriptor, isTransferDescriptor } from '../interface/transferable.js';
-import { TransportClient } from '../transport_client.js';
-import { DispatchMsg } from './create_dispatch_fn.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

@@ -1,58 +0,0 @@
-/**
- * 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

@@ -1,11 +0,0 @@
-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

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

package/src/transport/interface/listener.ts

@@ -1,16 +0,0 @@
-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 {
-  // eslint-disable-next-line jsdoc/require-jsdoc
-  open(): void;
-  // eslint-disable-next-line jsdoc/require-jsdoc
-  close(): void;
-  // eslint-disable-next-line jsdoc/require-jsdoc
-  on(name: 'new_socket', cb: (client: Socket) => void): this;
-}

package/src/transport/interface/socket.ts

@@ -1,15 +0,0 @@
-/**
- * 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 {
-  // eslint-disable-next-line jsdoc/require-jsdoc
-  send(msg: any, transfer?: Transferable[]): Promise<void>;
-  // eslint-disable-next-line jsdoc/require-jsdoc
-  registerHandler(cb: (msg: any) => any): void;
-  // eslint-disable-next-line jsdoc/require-jsdoc
-  close(): void;
-}

package/src/transport/interface/transferable.ts

@@ -1,125 +0,0 @@
-const $transferable = Symbol('thread.transferable');
-
-/**
- * Represents a descriptor for transferable objects in multi-threaded environments.
- * Provides a structure for marking certain objects as transferable and managing the ownership transfer
- * between threads, particularly useful when working with Web Workers.
- */
-export interface TransferDescriptor<T = any> {
-  /**
-   * A unique symbol indicating that an object is a TransferDescriptor.
-   */
-  [$transferable]: true;
-  /**
-   * The transferable data to be sent between threads.
-   */
-  send: T;
-  /**
-   * An array of objects that can be transferred between threads without serialization and deserialization.
-   */
-  transferables: Transferable[];
-}
-
-/**
- * Determines if the provided object is transferable.
- * Transferable objects are instances of a certain set of classes,
- * such as ArrayBuffer or MessagePort, which can be transferred between
- * different execution contexts (e.g., workers) without incurring the
- * overhead of serialization and deserialization.
- *
- * This function checks for the basic transferable criteria, but does not
- * perform an exhaustive check for all possible transferable types. As new
- * transferable types are added to JavaScript, they may be supported without
- * needing to modify this function.
- *
- * @param thing - The object to check for transferability.
- * @returns A boolean indicating whether the object is transferable.
- */
-function isTransferable(thing: any): thing is Transferable {
-  if (!thing || typeof thing !== 'object') {
-    return false;
-  }
-  // Don't check too thoroughly, since the list of transferable things in JS might grow over time
-  return true;
-}
-
-/**
- * Determines whether a given object is a TransferDescriptor.
- * A TransferDescriptor is an object with a [$transferable] property set to true and used for
- * transferring ownership of transferable objects between threads.
- * This function checks if the input object has the required properties to be considered
- * a valid TransferDescriptor.
- *
- * @param thing - The object to be checked for being a TransferDescriptor.
- * @returns True if the object is a TransferDescriptor, false otherwise.
- */
-export function isTransferDescriptor(thing: any): thing is TransferDescriptor {
-  return thing && typeof thing === 'object' && thing[$transferable];
-}
-
-/**
- * Mark a transferable object as such, so it will no be serialized and
- * deserialized on messaging with the main thread, but to transfer
- * ownership of it to the receiving thread.
- *
- * Only works with array buffers, message ports and few more special
- * types of objects, but it's much faster than serializing and
- * deserializing them.
- *
- * Note:
- * The transferable object cannot be accessed by this thread again
- * unless the receiving thread transfers it back again!
- *
- * @param transferable - Array buffer, message port or similar.
- * @see https://developers.google.com/web/updates/2011/12/Transferable-Objects-Lightning-Fast
- */
-export function Transfer<T>(transferable: Transferable): TransferDescriptor<T>;
-
-/**
- * Mark transferable objects within an arbitrary object or array as
- * being a transferable object. They will then not be serialized
- * and deserialized on messaging with the main thread, but ownership
- * of them will be transferred to the receiving thread.
- *
- * Only array buffers, message ports and few more special types of
- * objects can be transferred, but it's much faster than serializing and
- * deserializing them.
- *
- * Note:
- * The transferable object cannot be accessed by this thread again
- * unless the receiving thread transfers it back again!
- *
- * @param transferable - Array buffer, message port or similar.
- * @see https://developers.google.com/web/updates/2011/12/Transferable-Objects-Lightning-Fast
- */
-export function Transfer<T>(payload: T, transferables: Transferable[]): TransferDescriptor<T>;
-
-/**
- * Create a TransferDescriptor for transferable objects within an arbitrary object or array, allowing
- * them to be transferred between threads instead of being serialized and deserialized.
- * This method is particularly useful when working with Web Workers and other multi-threaded environments.
- * Transferable objects include ArrayBuffers, MessagePorts, and a few other special types.
- * Note that after transferring, the original thread will lose access to the transferred object unless
- * it's transferred back again.
- *
- * @param payload - The transferable object or an object containing transferable properties.
- * @param transferables - Optional array of Transferable objects found in the payload. If not provided,
- *                        the payload itself should be a Transferable object.
- * @returns A TransferDescriptor<T> containing the payload and transferables, marked as transferable.
- * @throws Error if payload is not transferable and transferables array is not provided.
- * @see https://developers.google.com/web/updates/2011/12/Transferable-Objects-Lightning-Fast
- */
-export function Transfer<T>(payload: T, transferables?: Transferable[]): TransferDescriptor<T> {
-  if (!transferables) {
-    if (!isTransferable(payload)) {
-      throw Error();
-    }
-    transferables = [payload];
-  }
-
-  return {
-    [$transferable]: true,
-    send: payload,
-    transferables,
-  };
-}

package/src/transport/node/index.ts

@@ -1,2 +0,0 @@
-export * from './node_connector.js';
-export * from './node_listener.js';

package/src/transport/node/node_connector.ts

@@ -1,30 +0,0 @@
-import { Worker } from 'worker_threads';
-
-import { Connector } from '../interface/connector.js';
-import { NodeConnectorSocket } from './node_connector_socket.js';
-
-/**
- * The NodeConnector class is a concrete implementation of the Connector interface, utilizing worker_threads for
- * efficient parallel execution. This class provides an easy way to establish a connection with a Worker instance,
- * allowing seamless communication via sockets.
- *
- * @example
- * const worker = new Worker('./path/to/worker.js');
- * const nodeConnector = new NodeConnector(worker);
- * const socket = await nodeConnector.createSocket();
- * socket.send('Hello from main thread!');
- */
-export class NodeConnector implements Connector {
-  constructor(private worker: Worker) {}
-
-  /**
-   * Creates a new instance of NodeConnectorSocket using the worker provided in the constructor.
-   * The createSocket method is used to establish connections using the worker_threads module,
-   * allowing for efficient and fast communication between different parts of the application.
-   *
-   * @returns A Promise that resolves to a newly created NodeConnectorSocket instance.
-   */
-  createSocket() {
-    return Promise.resolve(new NodeConnectorSocket(this.worker));
-  }
-}

package/src/transport/node/node_connector_socket.ts

@@ -1,52 +0,0 @@
-import { TransferListItem, Worker } from 'worker_threads';
-
-import { Socket } from '../interface/socket.js';
-
-/**
- * NodeConnectorSocket is a wrapper class that implements the Socket interface for messaging between
- * the main thread and worker threads in a Node.js environment. It uses the Worker API for
- * communication by sending and receiving messages through postMessage and handling messages using
- * event listeners.
- *
- * The send method sends messages to the worker thread, and the registerHandler method registers a
- * callback function to handle incoming messages from the worker. The close method cleans up
- * resources when the socket is no longer needed.
- */
-export class NodeConnectorSocket implements Socket {
-  constructor(private worker: Worker) {}
-
-  /**
-   * Sends a message from the NodeConnectorSocket instance to the associated worker thread.
-   * The 'msg' can be any data type and 'transfer' is an optional array of transferable objects
-   * that can be transferred with zero-copy semantics. The function returns a resolved Promise
-   * once the message has been posted.
-   *
-   * @param msg - The message to send to the worker thread.
-   * @param transfer - Optional array of Transferable objects to transfer ownership alongside the message.
-   * @returns A Promise that resolves when the message has been posted.
-   */
-  send(msg: any, transfer: Transferable[] = []): Promise<void> {
-    this.worker.postMessage(msg, transfer as TransferListItem[]);
-    return Promise.resolve();
-  }
-
-  /**
-   * Registers a callback function to handle incoming messages from the worker.
-   * The provided callback will be executed whenever a message is received from
-   * the worker, passing the message as its single argument.
-   *
-   * @param cb - The callback function to be called when a message is received.
-   */
-  registerHandler(cb: (msg: any) => any): void {
-    this.worker.on('message', cb);
-  }
-
-  /**
-   * Closes the worker connection and removes all event listeners.
-   * Sends an undefined message to the worker for graceful termination.
-   */
-  close() {
-    void this.send(undefined);
-    this.worker.removeAllListeners();
-  }
-}

package/src/transport/node/node_listener.ts

@@ -1,34 +0,0 @@
-import EventEmitter from 'events';
-import { parentPort } from 'worker_threads';
-
-import { Listener } from '../interface/listener.js';
-import { NodeListenerSocket } from './node_listener_socket.js';
-
-/**
- * NodeListener is an event-driven class that extends EventEmitter and implements the Listener interface.
- * It provides methods to open and close communication with a worker thread using the NodeListenerSocket.
- * The 'new_socket' event is emitted when a new NodeListenerSocket instance is created, allowing for
- * efficient processing of incoming messages from the parent thread.
- */
-export class NodeListener extends EventEmitter implements Listener {
-  constructor() {
-    super();
-  }
-
-  /**
-   * Opens a new connection to a parent worker thread and emits an event with the created NodeListenerSocket instance.
-   * The 'new_socket' event can be listened for, providing access to the newly created NodeListenerSocket.
-   *
-   * Fires NodeListener#new_socket.
-   */
-  open() {
-    this.emit('new_socket', new NodeListenerSocket(parentPort as any));
-  }
-
-  /**
-   * Closes the NodeListener instance.
-   * This method currently has no implementation, as there is no need to perform any actions
-   * when closing a NodeListener. It exists for compatibility with the Listener interface.
-   */
-  close() {}
-}

package/src/transport/node/node_listener_socket.ts

@@ -1,48 +0,0 @@
-import { MessagePort, TransferListItem } from 'worker_threads';
-
-import { Socket } from '../interface/socket.js';
-
-/**
- * An implementation of a TransportSocket using MessagePorts.
- */
-export class NodeListenerSocket implements Socket {
-  constructor(private port: MessagePort) {}
-
-  /**
-   * Sends a message through the MessagePort along with any provided Transferables.
-   * The transfer list allows for efficient sending of certain types of data,
-   * such as ArrayBuffer, ImageBitmap, and MessagePort.
-   * The Promise resolves once the message has been successfully sent.
-   *
-   * @param msg - The message to be sent through the MessagePort.
-   * @param transfer - An optional array of Transferable objects to be transferred.
-   * @returns A Promise that resolves once the message has been sent.
-   */
-  send(msg: any, transfer: Transferable[] = []): Promise<void> {
-    this.port.postMessage(msg, transfer as TransferListItem[]);
-    return Promise.resolve();
-  }
-
-  /**
-   * Registers a callback function to handle incoming messages from the MessagePort.
-   * When a message is received, the provided callback function will be invoked with
-   * the received message as its argument. This method allows for efficient and
-   * dynamic handling of incoming data in a NodeListenerSocket instance.
-   *
-   * @param cb - The callback function to process incoming messages.
-   */
-  registerHandler(cb: (msg: any) => any): void {
-    this.port.on('message', cb);
-  }
-
-  /**
-   * Closes the NodeListenerSocket instance, removing all listeners and closing the underlying MessagePort.
-   * Sends an undefined message to notify any connected ports about the closure before removing event listeners
-   * and cleaning up resources. This method should be called when the socket is no longer needed to avoid memory leaks.
-   */
-  close() {
-    void this.send(undefined);
-    this.port.removeAllListeners();
-    this.port.close();
-  }
-}