@procedures/client 0.45.0 → 0.47.1

package/src/procedures/module.ts

@@ -18,10 +18,10 @@
  * rule of a server all use the registry of the invocation (`ctx.registry`).
  */
 
-import { PROCEDURE_REGISTRY, ProcedureRegistry, RegistryError } from "./registry.js";
+import { PROCEDURE_REGISTRY, ProcedureRegistry, RegistryError, type RegistryResolver } from "./registry.js";
 import { coreProcedures } from "./core/index.js";
 import { metaProcedures as definitionProcedures } from "./define-procedure.js";
-import { pathToKey, type AnyProcedure, type ProcedureModule, type RegistrationOptions } from "./types.js";
+import { pathToKey, type AnyProcedure, type ProcedureModule, type ProcedurePath, type RegistrationOptions } from "./types.js";
 
 /**
  * The procedures of `@procedures/client`: the control flow (`client.chain`, `client.map` and the
@@ -139,6 +139,117 @@ export function createRegistry(...modules: ModuleInput[]): ProcedureRegistry {
   return registerModules(new ProcedureRegistry(), [clientModule, ...modules]);
 }
 
+/** The options of `createLazyRegistry()` (roadmap O93). */
+export interface LazyRegistryOptions {
+  /** The modules that the registry registers at once, after `clientModule`: the core procedures. */
+  readonly modules?: readonly ModuleInput[] | undefined;
+  /**
+   * The index: the key of each path (`pathToKey()`) and the names of the packages that give it.
+   * Two packages can give one path.
+   */
+  readonly index: Readonly<Record<string, readonly string[]>>;
+  /** This function gives the module of a package, or undefined for a package without a build. */
+  readonly load: (name: string) => Promise<ProcedureModule | undefined>;
+  /**
+   * The names of all packages, in the order of the eager load. `loadAll()` loads them in this
+   * order. The default is the names of the index.
+   */
+  readonly packages?: readonly string[] | undefined;
+  /** This function gets each warning. The default is `console.warn`. */
+  readonly warn?: ((message: string) => void) | undefined;
+}
+
+/** The first line of the message of an error. */
+function firstLine(error: unknown): string {
+  return (error instanceof Error ? error.message : String(error)).split("\n")[0] ?? "";
+}
+
+/**
+ * This function makes a lazy registry (roadmap O93). The registry has the procedures of
+ * `clientModule` and of `options.modules` at once. A miss of `resolve()` loads only the packages
+ * that the index names for the path.
+ *
+ * - Concurrent resolves of one package start one load.
+ * - A path that is not in the index loads each package, with one warning for each path.
+ * - A package that did not load gives a warning. The resolve of a path that is still missing
+ *   then rejects with a `RegistryError`, with the load error as its `cause`. A later resolve tries
+ *   that package again.
+ * - The registration goes through `registerModules()`: the modules that a module requires come
+ *   with it, and the same handler from two modules registers one time.
+ * - `loadAll()` loads each package in the order of `options.packages`.
+ */
+export function createLazyRegistry(options: LazyRegistryOptions): ProcedureRegistry {
+  const warn = options.warn ?? ((message: string): void => console.warn(message));
+  const packages = options.packages ?? [...new Set(Object.values(options.index).flat())];
+  const loaded = new Set<string>();
+  const inFlight = new Map<string, Promise<void>>();
+  const warnedPaths = new Set<string>();
+
+  function loadPackage(name: string): Promise<void> {
+    if (loaded.has(name)) return Promise.resolve();
+    const current = inFlight.get(name);
+    if (current) return current;
+    const started = (async (): Promise<void> => {
+      const module = await options.load(name);
+      if (module) registerModules(registry, [module]);
+    })();
+    inFlight.set(name, started);
+    // A failure is not recorded as a load: the next resolve tries the package again
+    started.then(
+      () => {
+        loaded.add(name);
+        inFlight.delete(name);
+      },
+      (error: unknown) => {
+        inFlight.delete(name);
+        warn(`the procedures of ${name} did not load: ${firstLine(error)}`);
+      },
+    );
+    return started;
+  }
+
+  const resolver: RegistryResolver = {
+    async resolve(path: ProcedurePath): Promise<void> {
+      const key = pathToKey(path);
+      const named = Object.hasOwn(options.index, key) ? options.index[key] : undefined;
+      let targets: readonly string[];
+      if (named !== undefined && named.length > 0) {
+        targets = named;
+      } else {
+        if (!warnedPaths.has(key)) {
+          warnedPaths.add(key);
+          warn(`the index has no package for ${key}: each package loads`);
+        }
+        targets = packages;
+      }
+      let failure: { name: string; error: unknown } | undefined;
+      // One package after the other, in the order of the index: the order of the eager load
+      for (const name of targets) {
+        try {
+          await loadPackage(name);
+        } catch (error) {
+          failure ??= { name, error };
+        }
+      }
+      if (failure === undefined || registry.has(path)) return;
+      const cause = failure.error instanceof Error ? failure.error : new Error(String(failure.error));
+      throw new RegistryError(`The procedure ${key} did not load: the package ${failure.name} did not load: ${firstLine(cause)}`, path, cause);
+    },
+    async loadAll(): Promise<void> {
+      for (const name of packages) {
+        try {
+          await loadPackage(name);
+        } catch {
+          // loadPackage() gave the warning. The other packages still load, as in the eager load.
+        }
+      }
+    },
+  };
+
+  const registry = new ProcedureRegistry({ resolver });
+  return registerModules(registry, [clientModule, ...(options.modules ?? [])]);
+}
+
 /**
  * This function registers the procedures of `clientModule` in a registry: the global registry by
  * default. A procedure that the registry has already stays. The `./register` entry of the package

package/src/procedures/ref.ts

@@ -57,7 +57,8 @@
  * ```
  */
 
-import type { ProcedurePath } from "./types.js";
+import { pathToKey, type ProcedurePath } from "./types.js";
+import type { ResolvingRegistry } from "./registry.js";
 
 // =============================================================================
 // Procedure Reference Constants
@@ -854,6 +855,62 @@ export function rawInputRule(
 
 const RAW_INPUT_RULES = new WeakMap<object, (path: ProcedurePath) => boolean>();
 
+/** The `$proc` paths of a value that the registry does not have yet, by key. */
+function missingRefPaths(registry: ResolvingRegistry, value: unknown): ProcedurePath[] {
+  const missing = new Map<string, ProcedurePath>();
+  const seen = new Set<object>();
+  const visit = (node: unknown): void => {
+    if (node === null || typeof node !== "object" || seen.has(node)) return;
+    seen.add(node);
+    if (isLiteral(node)) return;
+    if (Array.isArray(node)) {
+      for (const item of node) visit(item);
+      return;
+    }
+    if (isAnyProcedureRef(node)) {
+      try {
+        const ref = normalizeRef(node);
+        const path: unknown = ref.path;
+        if (Array.isArray(path) && path.length > 0 && path.every((segment) => typeof segment === "string") && registry.get(path) === undefined) {
+          missing.set(pathToKey(path), path);
+        }
+        visit(ref.input);
+      } catch {
+        // The run reports a ref that is not correct
+      }
+      return;
+    }
+    if (!isPlainObject(node)) return;
+    for (const field of Object.values(node)) visit(field);
+  };
+  visit(value);
+  return [...missing.values()];
+}
+
+/**
+ * This function loads the procedures of the `$proc` paths of a value into a lazy registry (roadmap
+ * O93). A run starts it before it reads the raw-input rule, because the rule is sync and reads only
+ * the procedures that have loaded. The function gives undefined, with no wait, for an eager
+ * registry and for a value whose paths the registry has. A package that does not load does not
+ * stop the run: the call of its path reports the error.
+ */
+export function preloadRefPaths(registry: ResolvingRegistry | undefined, value: unknown): Promise<void> | undefined {
+  if (registry?.lazy !== true || registry.resolve === undefined) return undefined;
+  const missing = missingRefPaths(registry, value);
+  if (missing.length === 0) return undefined;
+  const resolve = registry.resolve.bind(registry);
+  return (async (): Promise<void> => {
+    // One path after the other: the order of the registrations does not depend on the time of each load
+    for (const path of missing) {
+      try {
+        await resolve(path);
+      } catch {
+        // The call of the path reports the load error
+      }
+    }
+  })();
+}
+
 // =============================================================================
 // Template Extraction
 // =============================================================================

package/src/procedures/registry.ts

@@ -76,6 +76,60 @@ function samePath(a: ProcedurePath, b: ProcedurePath): boolean {
   return a.length === b.length && a.every((segment, index) => segment === b[index]);
 }
 
+// =============================================================================
+// Lazy Resolution (roadmap O93)
+// =============================================================================
+
+/**
+ * The resolver of a lazy registry: it loads procedures into the registry on demand.
+ * `createLazyRegistry()` gives one. An eager registry has no resolver.
+ */
+export interface RegistryResolver {
+  /**
+   * This method loads the packages that give the path. It rejects when a package did not load.
+   * A later call tries that package again.
+   */
+  resolve(path: ProcedurePath): Promise<void>;
+  /** This method loads each package. A package that did not load gives a warning, not a rejection. */
+  loadAll(): Promise<void>;
+}
+
+/** The options of `new ProcedureRegistry()`. */
+export interface ProcedureRegistryOptions {
+  /**
+   * The resolver of a lazy registry. Without it, the registry is eager: `resolve()` gives what
+   * `get()` gives, and `loadAll()` does nothing.
+   */
+  resolver?: RegistryResolver | undefined;
+}
+
+/** The reads of a registry that `resolveIn()` and `loadAllIn()` use. A lazy registry has all of them. */
+export interface ResolvingRegistry {
+  get(path: ProcedurePath): AnyProcedure | undefined;
+  readonly lazy?: boolean;
+  resolve?(path: ProcedurePath): Promise<AnyProcedure | undefined>;
+  loadAll?(): Promise<void>;
+}
+
+/**
+ * This function gives the procedure at a path of a registry. On a miss, a lazy registry loads the
+ * packages of the path. An eager registry gives what `get()` gives.
+ */
+export async function resolveIn(registry: ResolvingRegistry, path: ProcedurePath): Promise<AnyProcedure | undefined> {
+  const found = registry.get(path);
+  if (found !== undefined || registry.lazy !== true || registry.resolve === undefined) return found;
+  return registry.resolve(path);
+}
+
+/**
+ * This function loads each package of a lazy registry. A procedure that enumerates its registry
+ * (`procedure.list`, `procedure.manifest`, `mcp.listTools`) starts it first. On an eager
+ * registry, it does nothing.
+ */
+export async function loadAllIn(registry: Pick<ResolvingRegistry, "lazy" | "loadAll">): Promise<void> {
+  if (registry.lazy === true && registry.loadAll !== undefined) await registry.loadAll();
+}
+
 // =============================================================================
 // Procedure Registry
 // =============================================================================
@@ -113,6 +167,17 @@ export class ProcedureRegistry {
   /** Registered module names for debugging */
   private readonly registeredModules = new Set<string>();
 
+  /** The resolver of a lazy registry, or undefined for an eager registry (roadmap O93) */
+  private readonly resolver: RegistryResolver | undefined;
+
+  /**
+   * This constructor makes an eager registry. With `options.resolver`, the registry is lazy: a
+   * miss of `resolve()` loads the packages of the path.
+   */
+  constructor(options: ProcedureRegistryOptions = {}) {
+    this.resolver = options.resolver;
+  }
+
   // ---------------------------------------------------------------------------
   // Registration
   // ---------------------------------------------------------------------------
@@ -278,6 +343,40 @@ export class ProcedureRegistry {
     return this.procedures.size;
   }
 
+  // ---------------------------------------------------------------------------
+  // Lazy Resolution (roadmap O93)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * This property is true for a lazy registry. The sync reads (`get`, `has`, `getAll`,
+   * `getByPrefix`, `size`) of a lazy registry give only the procedures that have loaded.
+   */
+  get lazy(): boolean {
+    return this.resolver !== undefined;
+  }
+
+  /**
+   * This method gives the procedure at a path. A registered path gives its procedure at once. On
+   * a miss, a lazy registry loads the packages of the path first. An eager registry gives undefined.
+   *
+   * @throws RegistryError when the path is still missing and a package of the path did not load.
+   *   The load error is the `cause`.
+   */
+  async resolve(path: ProcedurePath): Promise<AnyProcedure | undefined> {
+    const found = this.get(path);
+    if (found || !this.resolver) return found;
+    await this.resolver.resolve(path);
+    return this.get(path);
+  }
+
+  /**
+   * This method loads each package of a lazy registry. After it, the sync reads give each
+   * procedure. On an eager registry, it does nothing.
+   */
+  async loadAll(): Promise<void> {
+    if (this.resolver) await this.resolver.loadAll();
+  }
+
   /**
    * Get all registered module names.
    */

package/src/procedures/segments.ts

@@ -24,7 +24,8 @@
  * ```
  */
 export function encodeSegment(segment: string): string {
-  return segment.replace(/[%.]/g, (char) => (char === "%" ? "%25" : "%2E"));
+  // Almost each segment has no `.` and no `%`: a test costs less than a replace with a callback (roadmap O90)
+  return /[%.]/.test(segment) ? segment.replace(/[%.]/g, (char) => (char === "%" ? "%25" : "%2E")) : segment;
 }
 
 /**
@@ -39,7 +40,8 @@ export function encodeSegment(segment: string): string {
  * ```
  */
 export function decodeSegment(segment: string): string {
-  return segment.replace(/%(25|2[Ee])/g, (_sequence, code: string) => (code === "25" ? "%" : "."));
+  // Almost each segment has no `%`: a test costs less than a replace with a callback (roadmap O90)
+  return segment.includes("%") ? segment.replace(/%(25|2[Ee])/g, (_sequence, code: string) => (code === "25" ? "%" : ".")) : segment;
 }
 
 /**
@@ -56,7 +58,14 @@ export function decodeSegment(segment: string): string {
 export function segmentsToTopic(segments: readonly string[]): string {
   // A segment that is not a string becomes text as with join(): null and undefined give "" (a
   // caller can check a path that is not valid, for example the compiler)
-  return segments.map((segment: unknown) => encodeSegment(segment === null || segment === undefined ? "" : String(segment))).join(".");
+  // The loop makes no array for each key: a key is made for each step of a call (roadmap O90)
+  let topic = "";
+  for (let index = 0; index < segments.length; index++) {
+    const segment: unknown = segments[index];
+    if (index > 0) topic += ".";
+    topic += encodeSegment(segment === null || segment === undefined ? "" : String(segment));
+  }
+  return topic;
 }
 
 /**

package/src/procedures/types.ts

@@ -442,6 +442,12 @@ export interface ProcedureRegistryLike {
   getAll(): AnyProcedure[];
   register(procedure: AnyProcedure, options?: RegistrationOptions): void;
   unregister(path: ProcedurePath): boolean;
+  /** This property is true for a lazy registry (roadmap O93). Its sync reads give only the procedures that have loaded. */
+  readonly lazy?: boolean;
+  /** This method gives the procedure at a path. A lazy registry loads the packages of the path on a miss. */
+  resolve?(path: ProcedurePath): Promise<AnyProcedure | undefined>;
+  /** This method loads each package of a lazy registry. A procedure that enumerates the registry starts it first. */
+  loadAll?(): Promise<void>;
 }
 
 /**

package/src/server/error-policy.ts

@@ -22,7 +22,8 @@
 
 import type { ProcedurePath } from "../procedures/types.js";
 import { closableUnread } from "../procedures/invoke.js";
-import { isKnownErrorCode } from "../client/errors/registry.js";
+// The codes only: the texts of ERROR_REGISTRY stay out of a bundle of the server (roadmap O95)
+import { isKnownCode as isKnownErrorCode } from "../client/errors/known-codes.js";
 import { errorCodeOf } from "../protocol.js";
 import { errorResponse, realErrorOf } from "./error-response.js";
 import { methodToPath } from "./method.js";

package/src/server/host-procedures.ts

@@ -9,7 +9,7 @@
  * checks that have no token.
  */
 
-import { z } from "zod";
+import * as z from "zod";
 import { createProcedure } from "../procedures/define.js";
 import { PURE_EFFECTS } from "../procedures/effects.js";
 import type { AnyProcedure } from "../procedures/types.js";
@@ -69,13 +69,17 @@ export function hostProcedures(source: HostSource): AnyProcedure[] {
     .input(z.object({}))
     .output(healthOutput)
     .meta({ description: "The health of the host: its state, its uptime and its calls in flight", effects: PURE_EFFECTS })
-    .handler(async () => ({
-      status: source.server.stopping ? ("stopping" as const) : ("ok" as const),
-      uptimeMs: Date.now() - source.startedAt,
-      procedures: source.server.procedureCount,
-      callsInFlight: source.server.inFlight(),
-      peerId: source.id,
-    }))
+    .handler(async () => {
+      // A lazy registry loads each package first: the count has each procedure (roadmap O93)
+      await source.server.loadAll();
+      return {
+        status: source.server.stopping ? ("stopping" as const) : ("ok" as const),
+        uptimeMs: Date.now() - source.startedAt,
+        procedures: source.server.procedureCount,
+        callsInFlight: source.server.inFlight(),
+        peerId: source.id,
+      };
+    })
     .build();
 
   const info = createProcedure()

package/src/server/procedure-server.ts

@@ -835,6 +835,16 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
     return procedure ? (request) => this.invoke(procedure, request) : null;
   }
 
+  /**
+   * A miss of a lazy registry loads the packages of the path, then the server looks up the
+   * handler again (roadmap O93). An eager registry, or a server that does not serve its registry,
+   * finds no handler here.
+   */
+  protected override findLateHandler(method: Method, request: ServerRequest<unknown>): Promise<ServerHandler | null> | null {
+    if (!this.servesRegistry || !this.procedureRegistry.lazy) return null;
+    return this.procedureRegistry.resolve(methodToPath(method)).then(() => this.findHandler(method, request));
+  }
+
   /**
    * Run a procedure for a request. A keyed call to a procedure that is not repeatable runs one
    * time for its key (R1).
@@ -1207,6 +1217,14 @@ export class ProcedureServer extends Server implements RepositoryProvider, StopP
     return this.servedKeys().size;
   }
 
+  /**
+   * This method loads each package of a lazy registry that the server serves (roadmap O93). Then
+   * `procedureCount` and the lists count each procedure. For an eager registry it does nothing.
+   */
+  async loadAll(): Promise<void> {
+    if (this.servesRegistry && this.procedureRegistry.lazy) await this.procedureRegistry.loadAll();
+  }
+
   /**
    * Check if the server serves a procedure now.
    *

package/src/server/server.ts

@@ -309,7 +309,8 @@ export class Server {
 
     try {
       // Find handler
-      const handler = this.findHandler(request.method, request);
+      // A miss can load the procedure first (a lazy registry, roadmap O93). A hit does not wait.
+      const handler = this.findHandler(request.method, request) ?? (await this.findLateHandler(request.method, request));
       if (!handler) {
         throw new HandlerNotFoundError(request.method);
       }
@@ -363,6 +364,14 @@ export class Server {
     return null;
   }
 
+  /**
+   * This method finds a handler after `findHandler()` found none. The default finds none at once.
+   * `ProcedureServer` loads the procedure of a lazy registry here (roadmap O93).
+   */
+  protected findLateHandler(_method: Method, _request: ServerRequest<unknown>): Promise<ServerHandler | null> | null {
+    return null;
+  }
+
   /**
    * Check if a method matches a matcher.
    */

package/src/testing/transport-contract.ts

@@ -25,7 +25,7 @@
  * (`ContractRunner`). Those of Vitest fit.
  */
 
-import { z } from "zod";
+import * as z from "zod";
 import {
   Client,
   VersionConflictError,

package/src/tracing/traceparent.ts

@@ -20,12 +20,35 @@ export interface TraceContext {
   readonly sampled: boolean;
 }
 
-function randomHex(bytes: number): string {
-  const values = new Uint8Array(bytes);
+/**
+ * The size of the pool of random bytes. One fill gives 256 trace ids or 512 span ids. Before
+ * (roadmap O94), each id called `getRandomValues` for 8 or 16 bytes: in a chain of 200 steps, the
+ * random ids took about 10 % of the per-step time of the host.
+ */
+export const RANDOM_POOL_BYTES = 4096;
+
+/** The two hex digits of each byte value. */
+const HEX = Array.from({ length: 256 }, (_, value) => value.toString(16).padStart(2, "0"));
+
+const pool = new Uint8Array(RANDOM_POOL_BYTES);
+// The pool starts empty: the first id fills it
+let next = RANDOM_POOL_BYTES;
+
+/** This function fills the pool with new random bytes. Each byte goes to one id only. */
+function refill(): void {
   const crypto = (globalThis as { crypto?: { getRandomValues?: (array: Uint8Array) => Uint8Array } }).crypto;
-  if (crypto?.getRandomValues) crypto.getRandomValues(values);
-  else for (let index = 0; index < bytes; index++) values[index] = Math.floor(Math.random() * 256);
-  return Array.from(values, (value) => value.toString(16).padStart(2, "0")).join("");
+  if (crypto?.getRandomValues) crypto.getRandomValues(pool);
+  else for (let index = 0; index < RANDOM_POOL_BYTES; index++) pool[index] = Math.floor(Math.random() * 256);
+  next = 0;
+}
+
+/** This function gives `bytes` random bytes of the pool as hex digits. `bytes` is 16 or less. */
+function randomHex(bytes: number): string {
+  if (next + bytes > RANDOM_POOL_BYTES) refill();
+  let hex = "";
+  for (let index = next; index < next + bytes; index++) hex += HEX[pool[index]!]!;
+  next += bytes;
+  return hex;
 }
 
 /** This function makes a new trace id: 32 random hex digits. */