@ricsam/isolate-client 0.1.5 → 0.1.6

package/README.md

@@ -18,6 +18,7 @@ npm add @ricsam/isolate-client
 - Module loader for custom ES module resolution
 - Custom functions callable from isolate code
 - Test environment and Playwright support
+- **Namespace-based runtime caching** for performance optimization
 
 ## Basic Usage
 
@@ -69,6 +70,79 @@ await runtime.dispose();
 await client.close();
 ```
 
+## Namespace-Based Runtime Caching
+
+For performance-critical applications, use **namespaces** to cache and reuse runtimes. Namespaced runtimes preserve their V8 isolate, context, and compiled module cache across dispose/create cycles:
+
+```typescript
+import { connect } from "@ricsam/isolate-client";
+
+const client = await connect({ socket: "/tmp/isolate.sock" });
+
+// Create a namespace for a tenant/user/session
+const namespace = client.createNamespace("tenant-123");
+
+// Create a runtime in this namespace
+const runtime = await namespace.createRuntime({
+  memoryLimitMB: 128,
+  moduleLoader: async (name) => loadModule(name),
+});
+
+console.log(runtime.reused); // false - first time
+
+// Import heavy modules (gets compiled and cached)
+await runtime.eval(`
+  import { heavyLibrary } from "@/heavy-module";
+  console.log("Module loaded!");
+`);
+
+// Dispose returns runtime to pool (soft-delete)
+await runtime.dispose();
+
+// Later: reuse the same namespace (same or different connection!)
+const client2 = await connect({ socket: "/tmp/isolate.sock" });
+const namespace2 = client2.createNamespace("tenant-123");
+const runtime2 = await namespace2.createRuntime({ /* options */ });
+
+console.log(runtime2.reused); // true - reused from pool!
+// Module cache preserved - no recompilation needed
+await runtime2.eval(`
+  import { heavyLibrary } from "@/heavy-module";  // instant!
+`);
+```
+
+### Namespace Interface
+
+```typescript
+interface Namespace {
+  /** The namespace ID */
+  readonly id: string;
+  /** Create a runtime in this namespace (cacheable on dispose) */
+  createRuntime(options?: RuntimeOptions): Promise<RemoteRuntime>;
+}
+```
+
+### What's Preserved vs Reset
+
+**Preserved on reuse (performance benefit):**
+- V8 Isolate instance
+- V8 Context
+- Compiled ES module cache
+- Global state and imported modules
+
+**Reset on reuse:**
+- Owner connection (new owner)
+- Callbacks (re-registered from new client)
+- Timers (cleared)
+- Console state (counters, timers, groups reset)
+
+### Behavior Notes
+
+- Non-namespaced runtimes (`client.createRuntime()`) work as before - true disposal
+- Namespaced runtimes are cached on dispose and evicted via LRU when `maxIsolates` limit is reached
+- Cross-client reuse is allowed - any connection can reuse a namespace by ID
+- A namespace can only have one active runtime at a time; creating a second runtime with the same namespace ID while one is active will fail
+
 ## Module Loader
 
 Register a custom module loader to handle dynamic `import()` calls:
@@ -340,7 +414,11 @@ await browser.close();
 ```typescript
 interface RemoteRuntime {
   readonly id: string;
+  /** True if runtime was reused from namespace pool */
+  readonly reused?: boolean;
+
   eval(code: string, filename?: string): Promise<void>;
+  /** Dispose runtime (soft-delete if namespaced, hard delete otherwise) */
   dispose(): Promise<void>;
 
   // Module handles
@@ -351,6 +429,17 @@ interface RemoteRuntime {
   readonly playwright: RemotePlaywrightHandle;
 }
 
+interface DaemonConnection {
+  /** Create a new runtime in the daemon */
+  createRuntime(options?: RuntimeOptions): Promise<RemoteRuntime>;
+  /** Create a namespace for runtime pooling/reuse */
+  createNamespace(id: string): Namespace;
+  /** Close the connection */
+  close(): Promise<void>;
+  /** Check if connected */
+  isConnected(): boolean;
+}
+
 interface RemoteFetchHandle {
   dispatchRequest(request: Request, options?: DispatchOptions): Promise<Response>;
   hasServeHandler(): Promise<boolean>;

package/dist/cjs/connection.cjs

@@ -49,7 +49,8 @@ async function connect(options = {}) {
     nextStreamId: 1,
     connected: true,
     streamResponses: new Map,
-    uploadStreams: new Map
+    uploadStreams: new Map,
+    moduleSourceCache: new Map
   };
   const parser = import_isolate_protocol.createFrameParser();
   socket.on("data", (data) => {
@@ -64,15 +65,38 @@ async function connect(options = {}) {
   socket.on("close", () => {
     state.connected = false;
     for (const [, pending] of state.pendingRequests) {
+      if (pending.timeoutId) {
+        clearTimeout(pending.timeoutId);
+      }
       pending.reject(new Error("Connection closed"));
     }
     state.pendingRequests.clear();
+    for (const [, receiver] of state.streamResponses) {
+      receiver.state = "errored";
+      receiver.error = new Error("Connection closed");
+      const resolvers = receiver.pullResolvers.splice(0);
+      for (const resolver of resolvers) {
+        resolver();
+      }
+    }
+    state.streamResponses.clear();
+    for (const [, session] of state.uploadStreams) {
+      session.state = "closed";
+      if (session.creditResolver) {
+        session.creditResolver();
+      }
+    }
+    state.uploadStreams.clear();
   });
   socket.on("error", (err) => {
     console.error("Socket error:", err);
   });
   return {
     createRuntime: (runtimeOptions) => createRuntime(state, runtimeOptions),
+    createNamespace: (id) => ({
+      id,
+      createRuntime: (runtimeOptions) => createRuntime(state, runtimeOptions, id)
+    }),
     close: async () => {
       state.connected = false;
       socket.destroy();
@@ -175,23 +199,35 @@ function handleMessage(message, state) {
         metadata: msg.metadata,
         controller: null,
         state: "active",
-        pendingChunks: []
+        pendingChunks: [],
+        pullResolvers: [],
+        controllerFinalized: false
       };
       const readableStream = new ReadableStream({
         start(controller) {
           receiver.controller = controller;
         },
         pull(_controller) {
+          if (receiver.controllerFinalized) {
+            return;
+          }
           while (receiver.pendingChunks.length > 0) {
             const chunk = receiver.pendingChunks.shift();
             receiver.controller.enqueue(chunk);
           }
           if (receiver.state === "closed") {
-            receiver.controller.close();
-            return;
+            if (!receiver.controllerFinalized) {
+              receiver.controllerFinalized = true;
+              receiver.controller.close();
+            }
+            return Promise.resolve();
           }
           if (receiver.state === "errored") {
-            return;
+            if (!receiver.controllerFinalized && receiver.error) {
+              receiver.controllerFinalized = true;
+              receiver.controller.error(receiver.error);
+            }
+            return Promise.resolve();
           }
           sendMessage(state.socket, {
             type: import_isolate_protocol.MessageType.STREAM_PULL,
@@ -199,17 +235,23 @@ function handleMessage(message, state) {
             maxBytes: import_isolate_protocol.STREAM_DEFAULT_CREDIT
           });
           return new Promise((resolve) => {
-            receiver.pullResolver = resolve;
+            receiver.pullResolvers.push(resolve);
           });
         },
         cancel(_reason) {
-          receiver.state = "errored";
+          receiver.state = "closed";
+          receiver.controllerFinalized = true;
+          const resolvers = receiver.pullResolvers.splice(0);
+          for (const resolver of resolvers) {
+            resolver();
+          }
           sendMessage(state.socket, {
             type: import_isolate_protocol.MessageType.STREAM_ERROR,
             streamId: msg.streamId,
             error: "Stream cancelled by consumer"
           });
           state.streamResponses.delete(msg.streamId);
+          return new Promise((resolve) => setTimeout(resolve, 0));
         }
       });
       state.streamResponses.set(msg.streamId, receiver);
@@ -236,10 +278,9 @@ function handleMessage(message, state) {
       const msg = message;
       const receiver = state.streamResponses.get(msg.streamId);
       if (receiver && receiver.state === "active") {
-        if (receiver.pullResolver) {
+        if (receiver.pullResolvers.length > 0) {
           receiver.controller.enqueue(msg.chunk);
-          const resolver = receiver.pullResolver;
-          receiver.pullResolver = undefined;
+          const resolver = receiver.pullResolvers.shift();
           resolver();
         } else {
           receiver.pendingChunks.push(msg.chunk);
@@ -256,10 +297,12 @@ function handleMessage(message, state) {
           const chunk = receiver.pendingChunks.shift();
           receiver.controller.enqueue(chunk);
         }
-        receiver.controller.close();
-        if (receiver.pullResolver) {
-          const resolver = receiver.pullResolver;
-          receiver.pullResolver = undefined;
+        if (!receiver.controllerFinalized) {
+          receiver.controllerFinalized = true;
+          receiver.controller.close();
+        }
+        const resolvers = receiver.pullResolvers.splice(0);
+        for (const resolver of resolvers) {
           resolver();
         }
         state.streamResponses.delete(msg.streamId);
@@ -288,10 +331,13 @@ function handleMessage(message, state) {
       const receiver = state.streamResponses.get(msg.streamId);
       if (receiver) {
         receiver.state = "errored";
-        receiver.controller.error(new Error(msg.error));
-        if (receiver.pullResolver) {
-          const resolver = receiver.pullResolver;
-          receiver.pullResolver = undefined;
+        receiver.error = new Error(msg.error);
+        while (receiver.pendingChunks.length > 0) {
+          const chunk = receiver.pendingChunks.shift();
+          receiver.controller.enqueue(chunk);
+        }
+        const resolvers = receiver.pullResolvers.splice(0);
+        for (const resolver of resolvers) {
           resolver();
         }
         state.streamResponses.delete(msg.streamId);
@@ -351,7 +397,7 @@ function sendRequest(state, message, timeout = DEFAULT_TIMEOUT) {
     sendMessage(state.socket, message);
   });
 }
-async function createRuntime(state, options = {}) {
+async function createRuntime(state, options = {}, namespaceId) {
   const callbacks = {};
   if (options.console) {
     callbacks.console = registerConsoleCallbacks(state, options.console);
@@ -474,11 +520,13 @@ async function createRuntime(state, options = {}) {
       memoryLimitMB: options.memoryLimitMB,
       cwd: options.cwd,
       callbacks,
-      testEnvironment: testEnvironmentOption
+      testEnvironment: testEnvironmentOption,
+      namespaceId
     }
   };
   const result = await sendRequest(state, request);
   const isolateId = result.isolateId;
+  const reused = result.reused ?? false;
   const wsCommandCallbacks = new Set;
   isolateWsCallbacks.set(isolateId, wsCommandCallbacks);
   const fetchHandle = {
@@ -722,6 +770,7 @@ async function createRuntime(state, options = {}) {
   return {
     id: isolateId,
     isolateId,
+    reused,
     fetch: fetchHandle,
     timers: timersHandle,
     console: consoleHandle,
@@ -855,7 +904,14 @@ function registerFsCallbacks(state, callbacks) {
 function registerModuleLoaderCallback(state, callback) {
   const callbackId = state.nextCallbackId++;
   state.callbacks.set(callbackId, async (moduleName) => {
-    return callback(moduleName);
+    const specifier = moduleName;
+    const cached = state.moduleSourceCache.get(specifier);
+    if (cached !== undefined) {
+      return cached;
+    }
+    const source = await callback(specifier);
+    state.moduleSourceCache.set(specifier, source);
+    return source;
   });
   return { callbackId, name: "moduleLoader", type: "async" };
 }
@@ -1182,4 +1238,4 @@ async function sendBodyStream(state, streamId, body) {
 }
 })
 
-//# debugId=5325684CDAEFBA9A64756E2164756E21
+//# debugId=6FA96113BD7C15F464756E2164756E21