@aztec/foundation 0.0.1-commit.733c4a3 → 0.0.1-commit.7689c7f

package/src/fifo/fifo_frame_reader.ts

@@ -0,0 +1,98 @@
+import EventEmitter from 'node:events';
+import * as fs from 'node:fs';
+import type { Readable } from 'node:stream';
+
+/**
+ * Events emitted by FifoFrameReader.
+ *
+ * - `frame`: A complete frame payload (without the 4-byte length header).
+ * - `error`: An unrecoverable error (invalid frame length, stream error).
+ * - `end`: The underlying stream has ended.
+ */
+export interface FifoFrameReaderEvents {
+  frame: [payload: Buffer];
+  error: [error: Error];
+  end: [];
+}
+
+/**
+ * Reads length-delimited frames from a readable stream (typically a named FIFO pipe).
+ *
+ * Wire format: `[4-byte big-endian payload length][payload bytes]`
+ *
+ * Emits a `frame` event for each complete frame with the raw payload buffer.
+ * Callers are responsible for deserializing the payload (e.g., via msgpack).
+ *
+ * On encountering an invalid payload length (0 or >maxPayloadSize), emits `error`
+ * and destroys the stream.
+ */
+export class FifoFrameReader extends EventEmitter<FifoFrameReaderEvents> {
+  private stream: Readable | null = null;
+  private pendingBuf: Buffer = Buffer.alloc(0);
+  private running = false;
+
+  constructor(private readonly maxPayloadSize = 10 * 1024 * 1024) {
+    super();
+  }
+
+  /** Open a FIFO at the given path and start reading frames. */
+  start(fifoPath: string, highWaterMark = 64 * 1024): void {
+    this.startFromStream(fs.createReadStream(fifoPath, { highWaterMark }));
+  }
+
+  /** Start reading frames from an existing readable stream. */
+  startFromStream(stream: Readable): void {
+    if (this.running) {
+      throw new Error('FifoFrameReader is already running');
+    }
+    this.running = true;
+    this.pendingBuf = Buffer.alloc(0);
+    this.stream = stream;
+
+    stream.on('data', (chunk: Buffer | string) => {
+      const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      this.pendingBuf = this.pendingBuf.length > 0 ? Buffer.concat([this.pendingBuf, buf]) : buf;
+      this.drainFrames();
+    });
+
+    stream.on('error', (err: Error) => {
+      if (this.running) {
+        this.emit('error', err);
+      }
+    });
+
+    stream.on('end', () => {
+      this.emit('end');
+    });
+  }
+
+  /** Stop reading and destroy the underlying stream. */
+  stop(): void {
+    this.running = false;
+    if (this.stream) {
+      this.stream.destroy();
+      this.stream = null;
+    }
+  }
+
+  /** Parse complete frames out of the pending buffer. */
+  private drainFrames(): void {
+    while (this.pendingBuf.length >= 4) {
+      const payloadLen = this.pendingBuf.readUInt32BE(0);
+      if (payloadLen === 0 || payloadLen > this.maxPayloadSize) {
+        this.emit('error', new Error(`Invalid payload length: ${payloadLen}`));
+        this.stop();
+        return;
+      }
+
+      const frameLen = 4 + payloadLen;
+      if (this.pendingBuf.length < frameLen) {
+        break; // Wait for more data
+      }
+
+      const payload = this.pendingBuf.subarray(4, frameLen);
+      this.pendingBuf = this.pendingBuf.subarray(frameLen);
+      this.emit('frame', Buffer.from(payload));
+    }
+  }
+}

package/src/fifo/index.ts

@@ -0,0 +1 @@
+export { FifoFrameReader } from './fifo_frame_reader.js';

package/src/fifo_set/fifo_set.ts

@@ -0,0 +1,52 @@
+/** A Set capped to a fixed number of entries, evicting the oldest inserted value when full. */
+export class FifoSet<T> extends Set<T> {
+  private _limit: number | undefined;
+
+  private constructor(values?: Iterable<T>) {
+    super(values);
+  }
+
+  /** Creates a bounded set with a positive integer limit. */
+  static withLimit<T>(limit: number, values?: Iterable<T>): FifoSet<T> {
+    if (!Number.isSafeInteger(limit) || limit <= 0) {
+      throw new TypeError(`FifoSet limit must be a positive safe integer: ${limit}`);
+    }
+
+    const set = new FifoSet(values);
+    set._limit = limit;
+    set.compact();
+
+    return set;
+  }
+
+  override add(value: T): this {
+    super.add(value);
+    this.compact();
+    return this;
+  }
+
+  /** Maximum number of entries retained by this set. */
+  public get limit(): number {
+    return this._limit ?? Infinity;
+  }
+
+  /** Evicts oldest entries until the set is within its limit. */
+  public compact(): void {
+    while (this.size > this.limit) {
+      const head = this.values().next();
+      if (head.done) {
+        return;
+      }
+      this.delete(head.value);
+    }
+  }
+
+  /** Adds a value only if it is absent, returning whether the set changed. */
+  public addIfAbsent(value: T): boolean {
+    if (this.has(value)) {
+      return false;
+    }
+    this.add(value);
+    return true;
+  }
+}

package/src/fifo_set/index.ts

@@ -0,0 +1 @@
+export * from './fifo_set.js';

package/src/jest/setup.mjs

@@ -10,3 +10,30 @@ import pretty from 'pino-pretty';
 if (!parseBooleanEnv(process.env.LOG_JSON)) {
   overwriteLoggingStream(pretty(pinoPrettyOpts));
 }
+
+// Prevent timers from keeping the process alive after tests complete.
+// Libraries like viem create internal polling loops (via setTimeout) that
+// reschedule themselves indefinitely. In test environments we never want a
+// timer to be the reason the process can't exit. We also unref stdout/stderr
+// which, when they are pipes (as in Jest workers), remain ref'd by default.
+{
+  const origSetTimeout = globalThis.setTimeout;
+  const origSetInterval = globalThis.setInterval;
+  globalThis.setTimeout = function unrefSetTimeout(...args) {
+    const id = origSetTimeout.apply(this, args);
+    id?.unref?.();
+    return id;
+  };
+  // Preserve .unref, .__promisify__ etc. that may exist on the original
+  Object.setPrototypeOf(globalThis.setTimeout, origSetTimeout);
+
+  globalThis.setInterval = function unrefSetInterval(...args) {
+    const id = origSetInterval.apply(this, args);
+    id?.unref?.();
+    return id;
+  };
+  Object.setPrototypeOf(globalThis.setInterval, origSetInterval);
+
+  if (process.stdout?._handle?.unref) process.stdout._handle.unref();
+  if (process.stderr?._handle?.unref) process.stderr._handle.unref();
+}

package/src/json-rpc/client/fetch.ts

@@ -43,17 +43,18 @@ export async function defaultFetch(
   }
 
   let responseJson;
+  const responseText = await resp.text();
   try {
-    responseJson = await resp.json();
+    responseJson = JSON.parse(responseText);
   } catch {
     if (!resp.ok) {
       throw new Error(resp.statusText);
     }
-    throw new Error(`Failed to parse body as JSON: ${await resp.text()}`);
+    throw new Error(`Failed to parse body as JSON: ${responseText}`);
   }
 
   if (!resp.ok) {
-    const errorMessage = `Error ${resp.status} from server ${host}: ${responseJson.error.message}`;
+    const errorMessage = `Error ${resp.status} from server ${host}: ${responseJson?.error?.message ?? JSON.stringify(responseJson)}`;
     if (noRetry || (resp.status >= 400 && resp.status < 500)) {
       throw new NoRetryError(errorMessage);
     } else {

package/src/json-rpc/client/safe_json_rpc_client.ts

@@ -2,7 +2,7 @@ import { format } from 'util';
 
 import { type Logger, createLogger } from '../../log/pino-logger.js';
 import { type PromiseWithResolvers, promiseWithResolvers } from '../../promise/utils.js';
-import { type ApiSchema, type ApiSchemaFor, schemaHasMethod } from '../../schemas/api.js';
+import { type ApiSchema, type ApiSchemaFor, getSchemaReturnType, schemaHasMethod } from '../../schemas/api.js';
 import { jsonStringify } from '../convert.js';
 import { type JsonRpcFetch, defaultFetch } from './fetch.js';
 
@@ -236,7 +236,7 @@ export function createSafeJsonRpcClient<T extends object>(
     if ([null, undefined, 'null', 'undefined'].includes(response.result)) {
       return;
     }
-    return (schema as ApiSchema)[methodName].returnType().parseAsync(response.result);
+    return getSchemaReturnType((schema as ApiSchema)[methodName]).parseAsync(response.result);
   };
 
   const clientId = nextClientId++;

package/src/json-rpc/client/undici.ts

@@ -44,18 +44,20 @@ export function makeUndiciFetch(client = new Agent()): JsonRpcFetch {
     let responseJson: any;
     const responseOk = resp.statusCode >= 200 && resp.statusCode <= 299;
     const contentEncoding = resp.headers['content-encoding'];
+    let responseText: string;
     try {
       if (contentEncoding === 'gzip') {
         const jsonBuffer = await gunzip(await resp.body.arrayBuffer());
-        responseJson = JSON.parse(jsonBuffer.toString('utf-8'));
+        responseText = jsonBuffer.toString('utf-8');
       } else {
-        responseJson = await resp.body.json();
+        responseText = await resp.body.text();
       }
+      responseJson = JSON.parse(responseText);
     } catch {
       if (!responseOk) {
         throw new Error('HTTP ' + resp.statusCode);
       }
-      throw new Error(`Failed to parse body as JSON. encoding: ${contentEncoding}, body: ${await resp.body.text()}`);
+      throw new Error(`Failed to parse body as JSON. encoding: ${contentEncoding}, body: ${responseText!}`);
     }
 
     if (!responseOk) {

package/src/json-rpc/fixtures/test_state.ts

@@ -130,14 +130,14 @@ export class TestState implements TestStateApi {
 }
 
 export const TestStateSchema: ApiSchemaFor<TestStateApi> = {
-  getNote: z.function().args(z.number()).returns(TestNote.schema.optional()),
-  getNotes: z.function().args(optional(schemas.Integer)).returns(z.array(TestNote.schema)),
-  getNotes2: z.function().args(optional(schemas.BigInt)).returns(z.array(TestNote.schema)),
-  getNotes3: z.function().args(optional(schemas.Integer)).returns(z.array(TestNote.schema)),
-  clear: z.function().returns(z.void()),
-  addNotes: z.function().args(z.array(TestNote.schema)).returns(z.array(TestNote.schema)),
-  fail: z.function().returns(z.void()),
-  count: z.function().returns(z.number()),
-  getStatus: z.function().returns(z.object({ status: z.string(), count: schemas.BigInt })),
-  getTuple: z.function().returns(z.tuple([z.string(), optional(z.string()), z.number()])),
+  getNote: z.function({ input: z.tuple([z.number()]), output: TestNote.schema.optional() }),
+  getNotes: z.function({ input: z.tuple([optional(schemas.Integer)]), output: z.array(TestNote.schema) }),
+  getNotes2: z.function({ input: z.tuple([optional(schemas.BigInt)]), output: z.array(TestNote.schema) }),
+  getNotes3: z.function({ input: z.tuple([optional(schemas.Integer)]), output: z.array(TestNote.schema) }),
+  clear: z.function({ input: z.tuple([]), output: z.void() }),
+  addNotes: z.function({ input: z.tuple([z.array(TestNote.schema)]), output: z.array(TestNote.schema) }),
+  fail: z.function({ input: z.tuple([]), output: z.void() }),
+  count: z.function({ input: z.tuple([]), output: z.number() }),
+  getStatus: z.function({ input: z.tuple([]), output: z.object({ status: z.string(), count: schemas.BigInt }) }),
+  getTuple: z.function({ input: z.tuple([]), output: z.tuple([z.string(), optional(z.string()), z.number()]) }),
 };

package/src/json-rpc/server/safe_json_rpc_server.ts

@@ -10,7 +10,13 @@ import { ZodError } from 'zod';
 
 import { type Logger, createLogger } from '../../log/index.js';
 import { promiseWithResolvers } from '../../promise/utils.js';
-import { type ApiSchema, type ApiSchemaFor, parseWithOptionals, schemaHasMethod } from '../../schemas/index.js';
+import {
+  type ApiSchema,
+  type ApiSchemaFor,
+  getSchemaParameters,
+  parseWithOptionals,
+  schemaHasMethod,
+} from '../../schemas/index.js';
 import { jsonStringify } from '../convert.js';
 import { assert } from '../js_utils.js';
 
@@ -53,8 +59,10 @@ export class SafeJsonRpcServer {
     config: Partial<SafeJsonRpcServerConfig> = {},
     /** Health check function */
     private readonly healthCheck: StatusCheckFn = () => true,
-    /** Additional middlewares */
+    /** Additional Koa middlewares */
     private extraMiddlewares: Application.Middleware[] = [],
+    /** Additional per-request diagnostics middlewares */
+    private diagnosticsMiddleware?: DiagnosticsMiddleware,
     /** Logger */
     private log = createLogger('json-rpc:server'),
   ) {
@@ -155,7 +163,7 @@ export class SafeJsonRpcServer {
           };
           return;
         }
-        const resp = await this.processBatch(ctx.request.body);
+        const resp = await this.processBatch(ctx.request.body, ctx.request.headers);
         if (Array.isArray(resp)) {
           ctx.status = 200;
           ctx.body = resp;
@@ -164,7 +172,7 @@ export class SafeJsonRpcServer {
           ctx.body = resp;
         }
       } else {
-        const resp = await this.processRequest(ctx.request.body);
+        const resp = await this.processRequest(ctx.request.body, ctx.request.headers);
         if ('error' in resp) {
           ctx.status = this.config.http200OnError ? 200 : 400;
         }
@@ -176,11 +184,11 @@ export class SafeJsonRpcServer {
     return router;
   }
 
-  private async processBatch(requests: any[]) {
+  private async processBatch(requests: any[], headers: http.IncomingHttpHeaders = {}) {
     if (requests.length === 0) {
       return { jsonrpc: '2.0', error: { code: -32600, message: 'Invalid Request' }, id: null };
     }
-    const results = await Promise.allSettled(requests.map(req => this.processRequest(req)));
+    const results = await Promise.allSettled(requests.map(req => this.processRequest(req, headers)));
     return results.map(res => {
       if (res.status === 'fulfilled') {
         return res.value;
@@ -191,7 +199,7 @@ export class SafeJsonRpcServer {
     });
   }
 
-  private async processRequest(request: any) {
+  private async processRequest(request: any, headers: http.IncomingHttpHeaders = {}) {
     if (!request || typeof request !== 'object') {
       return { jsonrpc: '2.0', error: { code: -32600, message: 'Invalid Request' }, id: null };
     }
@@ -206,7 +214,16 @@ export class SafeJsonRpcServer {
       return { jsonrpc, id, error: { code: -32601, message: `Method not found: ${method}` } };
     } else {
       try {
-        const result = await this.proxy.call(method, params);
+        let result: any;
+
+        if (this.diagnosticsMiddleware) {
+          await this.diagnosticsMiddleware({ id: id ?? null, method, params, headers }, async () => {
+            result = await this.proxy.call(method, params);
+          });
+        } else {
+          result = await this.proxy.call(method, params);
+        }
+
         return { jsonrpc, id, result };
       } catch (err: any) {
         if (err && err instanceof ZodError) {
@@ -309,7 +326,7 @@ export class SafeJsonProxy<T extends object = any> implements Proxy {
     assert(schemaHasMethod(this.schema, methodName), `Method ${methodName} not found in schema`);
     const method = this.handler[methodName as keyof T];
     assert(typeof method === 'function', `Method ${methodName} is not a function`);
-    const args = await parseWithOptionals(jsonParams, this.schema[methodName].parameters());
+    const args = await parseWithOptionals(jsonParams, getSchemaParameters(this.schema[methodName]));
     const ret = await method.apply(this.handler, args);
     this.log.debug(format('response', methodName, ret));
     return ret;
@@ -377,6 +394,7 @@ function makeAggregateHealthcheck(namedHandlers: NamespacedApiHandlers, log?: Lo
 export type SafeJsonRpcServerOptions = Partial<
   SafeJsonRpcServerConfig & {
     healthCheck: StatusCheckFn;
+    diagnostic: DiagnosticsMiddleware;
     log: Logger;
     middlewares: Application.Middleware[];
   }
@@ -391,10 +409,10 @@ export function createNamespacedSafeJsonRpcServer(
   handlers: NamespacedApiHandlers,
   options: Omit<SafeJsonRpcServerOptions, 'healthcheck'> = {},
 ): SafeJsonRpcServer {
-  const { middlewares, log } = options;
+  const { diagnostic, middlewares, log } = options;
   const proxy = new NamespacedSafeJsonProxy(handlers);
   const healthCheck = makeAggregateHealthcheck(handlers, log);
-  return new SafeJsonRpcServer(proxy, options, healthCheck, middlewares, log);
+  return new SafeJsonRpcServer(proxy, options, healthCheck, middlewares, diagnostic, log);
 }
 
 export function createSafeJsonRpcServer<T extends object = any>(
@@ -402,9 +420,9 @@ export function createSafeJsonRpcServer<T extends object = any>(
   schema: ApiSchemaFor<T>,
   options: SafeJsonRpcServerOptions = {},
 ) {
-  const { log, healthCheck, middlewares: extraMiddlewares } = options;
+  const { diagnostic, log, healthCheck, middlewares: extraMiddlewares } = options;
   const proxy = new SafeJsonProxy(handler, schema);
-  return new SafeJsonRpcServer(proxy, options, healthCheck, extraMiddlewares, log);
+  return new SafeJsonRpcServer(proxy, options, healthCheck, extraMiddlewares, diagnostic, log);
 }
 
 /**

package/src/log/bigint-utils.ts

@@ -11,6 +11,9 @@ export function convertBigintsToStrings(obj: unknown): unknown {
   }
 
   if (obj !== null && typeof obj === 'object') {
+    if (typeof (obj as any).toJSON === 'function') {
+      return convertBigintsToStrings((obj as any).toJSON());
+    }
     const result: Record<string, unknown> = {};
     for (const key in obj) {
       result[key] = convertBigintsToStrings((obj as Record<string, unknown>)[key]);

package/src/log/pino-logger.ts

@@ -21,6 +21,8 @@ export type LoggerBindings = {
   instanceId?: string;
 };
 
+const MAX_MODULE_NAME_LENGTH = 256;
+
 // Allow global hooks for providing default bindings.
 // Used by withLoggerBindings in pino-logger-server to propagate bindings via AsyncLocalStorage.
 type LogBindingsHandler = () => LoggerBindings | undefined;
@@ -48,7 +50,7 @@ function getBindingsFromHandlers(): LoggerBindings | undefined {
 }
 
 export function createLogger(module: string, bindings?: LoggerBindings): Logger {
-  module = module.replace(/^aztec:/, '');
+  module = module.slice(0, MAX_MODULE_NAME_LENGTH).replace(/^aztec:/, '');
 
   const resolvedBindings = { ...getBindingsFromHandlers(), ...bindings };
   const actor = resolvedBindings?.actor;
@@ -375,5 +377,20 @@ export type Logger = { [K in LogLevel]: LogFn } & { /** Error log function */ er
  * @returns A string with both the log message and the error message.
  */
 function formatErr(msg: string, err?: unknown): string {
-  return err ? `${msg}: ${inspect(err)}` : msg;
+  if (!err) {
+    return msg;
+  }
+
+  try {
+    return `${msg}: ${inspect(err)}`;
+  } catch {
+    // inspect can crash on error objects with broken property descriptors
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-base-to-string
+      return `${msg}: ${err instanceof Error ? `${err.name}: ${err.message}` : String(err)}`;
+    } catch {
+      // if even String(err) fails, return the original message with a note about the error
+      return `${msg}: [unserializable error]`;
+    }
+  }
 }

package/src/noir/noir_package_config.ts

@@ -10,26 +10,6 @@ const noirLocalDependencySchema = z.object({
   path: z.string(),
 });
 
-const noirPackageConfigSchema = z.object({
-  package: z.object({
-    name: z.string().default(''),
-    type: z.enum(['lib', 'contract', 'bin']).default('bin'),
-    entry: z.string().optional(),
-    description: z.string().optional(),
-    authors: z.array(z.string()).optional(),
-    // eslint-disable-next-line camelcase
-    compiler_version: z.string().optional(),
-    backend: z.string().optional(),
-    license: z.string().optional(),
-  }),
-  dependencies: z.record(z.union([noirGitDependencySchema, noirLocalDependencySchema])).default({}),
-});
-
-/**
- * Noir package configuration.
- */
-export type NoirPackageConfig = z.infer<typeof noirPackageConfigSchema>;
-
 /**
  * A remote package dependency.
  */
@@ -45,6 +25,38 @@ export type NoirLocalDependencyConfig = z.infer<typeof noirLocalDependencySchema
  */
 export type NoirDependencyConfig = NoirGitDependencyConfig | NoirLocalDependencyConfig;
 
+/**
+ * Noir package configuration.
+ */
+export type NoirPackageConfig = {
+  package: {
+    name: string;
+    type: 'lib' | 'contract' | 'bin';
+    entry?: string | undefined;
+    description?: string | undefined;
+    authors?: string[] | undefined;
+    compiler_version?: string | undefined;
+    backend?: string | undefined;
+    license?: string | undefined;
+  };
+  dependencies: Record<string, NoirDependencyConfig>;
+};
+
+const noirPackageConfigSchema: z.ZodType<NoirPackageConfig> = z.object({
+  package: z.object({
+    name: z.string().default(''),
+    type: z.enum(['lib', 'contract', 'bin']).default('bin'),
+    entry: z.string().optional(),
+    description: z.string().optional(),
+    authors: z.array(z.string()).optional(),
+    // eslint-disable-next-line camelcase
+    compiler_version: z.string().optional(),
+    backend: z.string().optional(),
+    license: z.string().optional(),
+  }),
+  dependencies: z.record(z.string(), z.union([noirGitDependencySchema, noirLocalDependencySchema])).default({}),
+});
+
 /**
  * Checks that an object is a package configuration.
  * @param config - Config to check

package/src/queue/batch_queue.ts

@@ -105,6 +105,7 @@ export class BatchQueue<T, K extends string | number> {
       return Promise.resolve();
     }
 
+    this.flushCurrentBatch();
     this.container.end();
     return runningPromise;
   }

package/src/retry/index.ts

@@ -104,6 +104,36 @@ export async function retryUntil<T>(
   }
 }
 
+/**
+ * Retry an asynchronous function until it returns a truthy value or the maximum number of retries is exceeded.
+ * The function is retried periodically with a fixed interval between attempts.
+ *
+ * @param fn - The asynchronous function to be retried, which should return a truthy value upon success or undefined otherwise.
+ * @param name - The optional name of the operation, used for generating error messages.
+ * @param maxRetries - The maximum number of retry attempts before throwing an error.
+ * @param retryInterval - The optional interval, in seconds, between retry attempts. Defaults to 1 second.
+ * @returns A Promise that resolves with the successful (truthy) result of the provided function, or rejects if retries are exhausted.
+ */
+export async function retryTimes<T>(
+  fn: () => (T | undefined) | Promise<T | undefined>,
+  name = '',
+  maxRetries: number,
+  retryInterval = 1,
+) {
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const result = await fn();
+    if (result) {
+      return result;
+    }
+
+    if (attempt < maxRetries) {
+      await sleep(retryInterval * 1000);
+    }
+  }
+
+  throw new Error(name ? `Retries exhausted awaiting ${name}` : 'Retries exhausted');
+}
+
 /**
  * Convenience wrapper around retryUntil with fast polling for tests.
  * Uses 10s timeout and 100ms polling interval by default.

package/src/schemas/api.ts

@@ -2,32 +2,19 @@ import type { z } from 'zod';
 
 import type { ZodNullableOptional } from './utils.js';
 
-// Forces usage of ZodNullableOptional in parameters schemas so we properly accept nulls for optional parameters.
-type ZodParameterTypeFor<T> = undefined extends T
-  ? ZodNullableOptional<z.ZodType<T, z.ZodTypeDef, any>>
-  : z.ZodType<T, z.ZodTypeDef, any>;
-
-type ZodReturnTypeFor<T> = z.ZodType<T, z.ZodTypeDef, any>;
-
-// This monstruosity is used for mapping function arguments to their schema representation.
-// The complexity is required to satisfy ZodTuple which requires a fixed length tuple and
-// has a very annoying type of [] | [ZodTypeAny, ...ZodTypeAny], and most types fail to match
-// the second option. While a purely recursive approach works, it fails when trying to deal
-// with optional arguments (ie optional items in the tuple), and ts does not really like them
-// during a recursion and fails with infinite stack depth.
-// This type appears to satisfy everyone. Everyone but me.
-type ZodMapParameterTypes<T> = T extends []
-  ? []
-  : T extends [item: infer Head, ...infer Rest]
-    ? [ZodParameterTypeFor<Head>, ...{ [K in keyof Rest]: ZodParameterTypeFor<Rest[K]> }]
-    : T extends [item?: infer Head, ...infer Rest]
-      ? [ZodNullableOptional<ZodParameterTypeFor<Head>>, ...{ [K in keyof Rest]: ZodParameterTypeFor<Rest[K]> }]
-      : never;
+// Forces usage of schemas that accept nulls for optional parameters.
+type ZodParameterTypeFor<T> = undefined extends T ? ZodNullableOptional<z.ZodType<T, any>> : z.ZodType<T, any>;
+
+type ZodReturnTypeFor<T> = z.ZodType<T, any>;
+
+type ZodMapParameterTypes<T extends readonly unknown[]> = {
+  [K in keyof T]-?: ZodParameterTypeFor<T[K]>;
+};
 
 /** Maps all functions in an interface to their schema representation. */
 export type ApiSchemaFor<T> = {
   [K in keyof T]: T[K] extends (...args: infer Args) => Promise<infer Ret>
-    ? z.ZodFunction<z.ZodTuple<ZodMapParameterTypes<Args>, z.ZodUnknown>, ZodReturnTypeFor<Ret>>
+    ? z.ZodFunction<z.ZodTuple<ZodMapParameterTypes<Args>, null>, ZodReturnTypeFor<Ret>>
     : never;
 };
 
@@ -37,11 +24,24 @@ export type ApiSchema = {
 };
 
 /** Return whether an API schema defines a valid function schema for a given method name. */
-export function schemaHasMethod(schema: ApiSchema, methodName: string) {
+export function schemaHasMethod<T extends ApiSchema>(
+  schema: T,
+  methodName: string,
+): methodName is Extract<keyof T, string> {
   return (
     typeof methodName === 'string' &&
     Object.hasOwn(schema, methodName) &&
-    typeof schema[methodName].parameters === 'function' &&
-    typeof schema[methodName].returnType === 'function'
+    schema[methodName].def.input !== undefined &&
+    schema[methodName].def.output !== undefined
   );
 }
+
+/** Returns the parameter tuple schema for an API method schema. */
+export function getSchemaParameters<T extends z.ZodFunction<z.ZodTuple<any, any>, z.ZodTypeAny>>(schema: T) {
+  return schema.def.input;
+}
+
+/** Returns the return value schema for an API method schema. */
+export function getSchemaReturnType<T extends z.ZodFunction<z.ZodTuple<any, any>, z.ZodTypeAny>>(schema: T) {
+  return schema.def.output;
+}