refactor(shared): establish lazy runtime loader foundation

RomneyDa · RomneyDa · commit 66731b504bcc · 2026-07-02T16:46:27.000-07:00
diff --git a/src/library.ts b/src/library.ts
@@ -20,6 +20,7 @@ import type {
   runCommandWithTimeout as runCommandWithTimeoutRuntime,
   runExec as runExecRuntime,
 } from "./process/exec.js";
+import { createLazyRuntimeModule } from "./shared/lazy-runtime.js";
 import { normalizeE164 } from "./utils.js";
 
 type GetReplyFromConfig = typeof getReplyFromConfigRuntime;
@@ -29,38 +30,13 @@ type RunExec = typeof runExecRuntime;
 type RunCommandWithTimeout = typeof runCommandWithTimeoutRuntime;
 type MonitorWebChannel = typeof monitorWebChannelRuntime;
 
-let replyRuntimePromise: Promise<typeof import("./auto-reply/reply.runtime.js")> | null = null;
-let promptRuntimePromise: Promise<typeof import("./cli/prompt.js")> | null = null;
-let binariesRuntimePromise: Promise<typeof import("./infra/binaries.js")> | null = null;
-let execRuntimePromise: Promise<typeof import("./process/exec.js")> | null = null;
-let webChannelRuntimePromise: Promise<
-  typeof import("./plugins/runtime/runtime-web-channel-plugin.js")
-> | null = null;
-
-function loadReplyRuntime() {
-  replyRuntimePromise ??= import("./auto-reply/reply.runtime.js");
-  return replyRuntimePromise;
-}
-
-function loadPromptRuntime() {
-  promptRuntimePromise ??= import("./cli/prompt.js");
-  return promptRuntimePromise;
-}
-
-function loadBinariesRuntime() {
-  binariesRuntimePromise ??= import("./infra/binaries.js");
-  return binariesRuntimePromise;
-}
-
-function loadExecRuntime() {
-  execRuntimePromise ??= import("./process/exec.js");
-  return execRuntimePromise;
-}
-
-function loadWebChannelRuntime() {
-  webChannelRuntimePromise ??= import("./plugins/runtime/runtime-web-channel-plugin.js");
-  return webChannelRuntimePromise;
-}
+const loadReplyRuntime = createLazyRuntimeModule(() => import("./auto-reply/reply.runtime.js"));
+const loadPromptRuntime = createLazyRuntimeModule(() => import("./cli/prompt.js"));
+const loadBinariesRuntime = createLazyRuntimeModule(() => import("./infra/binaries.js"));
+const loadExecRuntime = createLazyRuntimeModule(() => import("./process/exec.js"));
+const loadWebChannelRuntime = createLazyRuntimeModule(
+  () => import("./plugins/runtime/runtime-web-channel-plugin.js"),
+);
 
 export const getReplyFromConfig: GetReplyFromConfig = async (...args) =>
   (await loadReplyRuntime()).getReplyFromConfig(...args);
diff --git a/src/shared/lazy-promise.test.ts b/src/shared/lazy-promise.test.ts
@@ -1,16 +1,30 @@
 // Lazy promise tests cover single-flight loading and error reuse behavior.
 import { describe, expect, it, vi } from "vitest";
-import { createLazyImportLoader, createLazyPromiseLoader } from "./lazy-promise.js";
+import {
+  createLazyImportLoader,
+  createLazyPromise,
+  createLazyPromiseLoader,
+} from "./lazy-promise.js";
+
+describe("createLazyPromise", () => {
+  it("returns a reusable single-flight loader", async () => {
+    let calls = 0;
+    const load = createLazyPromise(async () => `loaded-${++calls}`);
+
+    await expect(Promise.all([load(), load()])).resolves.toEqual(["loaded-1", "loaded-1"]);
+    await expect(load()).resolves.toBe("loaded-1");
+    expect(calls).toBe(1);
+  });
+});
 
 describe("createLazyPromiseLoader", () => {
   it("dedupes concurrent loads and reuses the resolved value", async () => {
     let calls = 0;
     const loader = createLazyPromiseLoader(async () => `loaded-${++calls}`);
+    const first = loader.load();
 
-    await expect(Promise.all([loader.load(), loader.load()])).resolves.toEqual([
-      "loaded-1",
-      "loaded-1",
-    ]);
+    expect(loader.load()).toBe(first);
+    await expect(first).resolves.toBe("loaded-1");
     await expect(loader.load()).resolves.toBe("loaded-1");
     expect(calls).toBe(1);
   });
@@ -45,8 +59,11 @@ describe("createLazyPromiseLoader", () => {
     let calls = 0;
     const loader = createLazyPromiseLoader(() => `loaded-${++calls}`);
 
+    expect(loader.peek()).toBeUndefined();
     await expect(loader.load()).resolves.toBe("loaded-1");
+    await expect(loader.peek()).resolves.toBe("loaded-1");
     loader.clear();
+    expect(loader.peek()).toBeUndefined();
     await expect(loader.load()).resolves.toBe("loaded-2");
   });
 });
diff --git a/src/shared/lazy-promise.ts b/src/shared/lazy-promise.ts
@@ -1,9 +1,11 @@
 /** Manual-control promise cache for lazy runtime resources. */
 export type LazyPromiseLoader<T> = {
   /** Resolves the cached value, creating one load promise when needed. */
-  load(): Promise<T>;
+  load: () => Promise<T>;
+  /** Returns the current cached promise without starting a load. */
+  peek: () => Promise<T> | undefined;
   /** Drops the cached promise so the next load starts fresh. */
-  clear(): void;
+  clear: () => void;
 };
 
 /** Options for controlling lazy promise cache behavior. */
@@ -38,16 +40,28 @@ export function createLazyPromiseLoader<T>(
   };
 
   return {
-    async load(): Promise<T> {
+    load(): Promise<T> {
       promise ??= createPromise();
-      return await promise;
+      return promise;
+    },
+    peek(): Promise<T> | undefined {
+      return promise;
     },
     clear(): void {
       promise = undefined;
     },
   };
 }
 
+/** Creates a reusable function that resolves one cached promise at a time. */
+export function createLazyPromise<T>(
+  load: () => T | Promise<T>,
+  options?: LazyPromiseLoaderOptions,
+): () => Promise<T> {
+  const loader = createLazyPromiseLoader(load, options);
+  return () => loader.load();
+}
+
 /** Convenience wrapper for dynamic-import-shaped loaders. */
 export function createLazyImportLoader<T>(
   load: () => Promise<T>,
diff --git a/src/shared/lazy-runtime.test.ts b/src/shared/lazy-runtime.test.ts
@@ -0,0 +1,37 @@
+import { describe, expect, it, vi } from "vitest";
+import { createLazyRuntimeModule, createLazyRuntimeSurface } from "./lazy-runtime.js";
+
+describe("lazy runtime helpers", () => {
+  it("caches imported modules", async () => {
+    const importer = vi.fn(async () => ({ value: "module" }));
+    const load = createLazyRuntimeModule(importer);
+    const first = load();
+
+    expect(load()).toBe(first);
+    expect(load.peek()).toBe(first);
+    await expect(first).resolves.toEqual({ value: "module" });
+    expect(importer).toHaveBeenCalledOnce();
+  });
+
+  it("can clear imported modules", async () => {
+    const importer = vi.fn(async () => ({ value: "module" }));
+    const load = createLazyRuntimeModule(importer);
+
+    await load();
+    load.clear();
+    expect(load.peek()).toBeUndefined();
+    await load();
+    expect(importer).toHaveBeenCalledTimes(2);
+  });
+
+  it("preserves cached runtime import rejections", async () => {
+    const importer = vi.fn(async () => {
+      throw new Error("sticky");
+    });
+    const load = createLazyRuntimeSurface(importer, (module) => module);
+
+    await expect(load()).rejects.toThrow("sticky");
+    await expect(load()).rejects.toThrow("sticky");
+    expect(importer).toHaveBeenCalledOnce();
+  });
+});
diff --git a/src/shared/lazy-runtime.ts b/src/shared/lazy-runtime.ts
@@ -1,19 +1,31 @@
+import { createLazyPromiseLoader } from "./lazy-promise.js";
+
+export { createLazyPromise, createLazyPromiseLoader } from "./lazy-promise.js";
+export type { LazyPromiseLoader } from "./lazy-promise.js";
+
+type LazyRuntimeLoader<T> = (() => Promise<T>) & {
+  peek: () => Promise<T> | undefined;
+  clear: () => void;
+};
+
 // Lazy runtime helpers expose dynamic imports through cached runtime surfaces.
 export function createLazyRuntimeSurface<TModule, TSurface>(
   importer: () => Promise<TModule>,
   select: (module: TModule) => TSurface,
-): () => Promise<TSurface> {
-  let cached: Promise<TSurface> | null = null;
-  return () => {
-    cached ??= importer().then(select);
-    return cached;
-  };
+): LazyRuntimeLoader<TSurface> {
+  const loader = createLazyPromiseLoader(() => importer().then(select), {
+    cacheRejections: true,
+  });
+  const load = loader.load as LazyRuntimeLoader<TSurface>;
+  load.peek = loader.peek;
+  load.clear = loader.clear;
+  return load;
 }
 
 /** Cache the raw dynamically imported runtime module behind a stable loader. */
 export function createLazyRuntimeModule<TModule>(
   importer: () => Promise<TModule>,
-): () => Promise<TModule> {
+): LazyRuntimeLoader<TModule> {
   return createLazyRuntimeSurface(importer, (module) => module);
 }
 
