@scelar/nodepod 1.0.4 → 1.0.6

package/dist/sdk/nodepod.d.ts

@@ -19,6 +19,7 @@ export declare class Nodepod {
     private _sharedVFS;
     private _syncChannel;
     private _unwatchVFS;
+    private _handler;
     private constructor();
     static boot(opts?: NodepodOptions): Promise<Nodepod>;
     spawn(cmd: string, args?: string[], opts?: SpawnOptions): Promise<NodepodProcess>;
@@ -27,10 +28,28 @@ export declare class Nodepod {
     setPreviewScript(script: string): Promise<void>;
     clearPreviewScript(): Promise<void>;
     port(num: number): string | null;
-    private static readonly SHALLOW_EXCLUDE;
+    /** Directory names excluded from snapshots at any depth when shallow=true. */
+    private static readonly SHALLOW_EXCLUDE_DIRS;
     snapshot(opts?: SnapshotOptions): Snapshot;
     restore(snapshot: Snapshot, opts?: SnapshotOptions): Promise<void>;
     teardown(): void;
+    memoryStats(): {
+        vfs: {
+            fileCount: number;
+            totalBytes: number;
+            dirCount: number;
+            watcherCount: number;
+        };
+        engine: {
+            moduleCacheSize: number;
+            transformCacheSize: number;
+        };
+        heap: {
+            usedMB: number;
+            totalMB: number;
+            limitMB: number;
+        } | null;
+    };
     get volume(): MemoryVolume;
     get engine(): ScriptEngine;
     get packages(): DependencyInstaller;

package/dist/sdk/types.d.ts

@@ -1,4 +1,5 @@
 import type { VolumeSnapshot } from "../engine-types";
+import type { MemoryHandlerOptions } from "../memory-handler";
 export interface NodepodOptions {
     files?: Record<string, string | Uint8Array>;
     env?: Record<string, string>;
@@ -7,6 +8,10 @@ export interface NodepodOptions {
     onServerReady?: (port: number, url: string) => void;
     /** Show a small "nodepod" watermark link in preview iframes. Defaults to true. */
     watermark?: boolean;
+    /** Memory optimization settings. Omit to use defaults. */
+    memory?: MemoryHandlerOptions;
+    /** Cache installed node_modules in IndexedDB for faster re-boots. Default: true. */
+    enableSnapshotCache?: boolean;
 }
 export interface TerminalTheme {
     background?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scelar/nodepod",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Browser-native Node.js runtime environment",
   "type": "module",
   "license": "MIT WITH Commons-Clause",

package/src/index.ts

@@ -170,6 +170,8 @@ export type {
   Snapshot,
   SpawnOptions,
 } from "./sdk/types";
+export { MemoryHandler, LRUCache } from "./memory-handler";
+export type { MemoryHandlerOptions } from "./memory-handler";
 
 /* ---- Threading / Worker Infrastructure ---- */
 

package/src/memory-handler.ts

@@ -0,0 +1,168 @@
+// Centralized memory optimization handler for Nodepod.
+// Provides LRU caches, heap monitoring, and pressure callbacks.
+
+import type { FileStat } from './memory-volume';
+
+/* ---- LRU Cache ---- */
+
+export class LRUCache<K, V> {
+  private _map = new Map<K, V>();
+  private _capacity: number;
+
+  constructor(capacity: number) {
+    this._capacity = Math.max(1, capacity);
+  }
+
+  get(key: K): V | undefined {
+    if (!this._map.has(key)) return undefined;
+    const value = this._map.get(key)!;
+    // Move to most-recently-used position
+    this._map.delete(key);
+    this._map.set(key, value);
+    return value;
+  }
+
+  set(key: K, value: V): void {
+    if (this._map.has(key)) {
+      this._map.delete(key);
+    } else if (this._map.size >= this._capacity) {
+      // Evict least-recently-used (first entry in Map)
+      const oldest = this._map.keys().next().value;
+      if (oldest !== undefined) this._map.delete(oldest);
+    }
+    this._map.set(key, value);
+  }
+
+  has(key: K): boolean {
+    return this._map.has(key);
+  }
+
+  delete(key: K): boolean {
+    return this._map.delete(key);
+  }
+
+  clear(): void {
+    this._map.clear();
+  }
+
+  get size(): number {
+    return this._map.size;
+  }
+
+  keys(): IterableIterator<K> {
+    return this._map.keys();
+  }
+
+  values(): IterableIterator<V> {
+    return this._map.values();
+  }
+}
+
+/* ---- Options ---- */
+
+export interface MemoryHandlerOptions {
+  /** LRU capacity for path normalization cache. Default: 2048 */
+  pathNormCacheSize?: number;
+  /** LRU capacity for stat result cache. Default: 512 */
+  statCacheSize?: number;
+  /** LRU capacity for module resolve cache. Default: 4096 */
+  resolveCacheSize?: number;
+  /** LRU capacity for package.json manifest cache. Default: 256 */
+  manifestCacheSize?: number;
+  /** LRU capacity for source transform cache. Default: 512 */
+  transformCacheSize?: number;
+  /** Max modules before trimming node_modules entries. Default: 512 */
+  moduleSoftCacheSize?: number;
+  /** Heap usage threshold in MB to trigger pressure callbacks. Default: 350 */
+  heapWarnThresholdMB?: number;
+  /** Monitoring poll interval in ms. Default: 30000 */
+  monitorIntervalMs?: number;
+  /** Max process stdout/stderr accumulation in bytes. Default: 4194304 (4MB) */
+  maxProcessOutputBytes?: number;
+}
+
+const DEFAULTS: Required<MemoryHandlerOptions> = {
+  pathNormCacheSize: 2048,
+  statCacheSize: 512,
+  resolveCacheSize: 4096,
+  manifestCacheSize: 256,
+  transformCacheSize: 512,
+  moduleSoftCacheSize: 512,
+  heapWarnThresholdMB: 350,
+  monitorIntervalMs: 30_000,
+  maxProcessOutputBytes: 4_194_304,
+};
+
+/* ---- MemoryHandler ---- */
+
+export class MemoryHandler {
+  readonly options: Required<MemoryHandlerOptions>;
+  readonly pathNormCache: LRUCache<string, string>;
+  readonly statCache: LRUCache<string, FileStat>;
+  readonly transformCache: LRUCache<string, string>;
+
+  private _monitorTimer: ReturnType<typeof setInterval> | null = null;
+  private _pressureCallbacks: Array<() => void> = [];
+  private _destroyed = false;
+
+  constructor(opts?: MemoryHandlerOptions) {
+    this.options = { ...DEFAULTS, ...opts };
+    this.pathNormCache = new LRUCache(this.options.pathNormCacheSize);
+    this.statCache = new LRUCache(this.options.statCacheSize);
+    this.transformCache = new LRUCache(this.options.transformCacheSize);
+  }
+
+  /** Invalidate a cached stat entry (call on file write/delete). */
+  invalidateStat(normalizedPath: string): void {
+    this.statCache.delete(normalizedPath);
+  }
+
+  /** Register a callback to be invoked when heap pressure is detected. Returns unsubscribe fn. */
+  onPressure(cb: () => void): () => void {
+    this._pressureCallbacks.push(cb);
+    return () => {
+      const idx = this._pressureCallbacks.indexOf(cb);
+      if (idx >= 0) this._pressureCallbacks.splice(idx, 1);
+    };
+  }
+
+  /** Start periodic heap monitoring. */
+  startMonitoring(): void {
+    if (this._monitorTimer || this._destroyed) return;
+    this._monitorTimer = setInterval(() => this._checkHeap(), this.options.monitorIntervalMs);
+  }
+
+  /** Stop monitoring. */
+  stopMonitoring(): void {
+    if (this._monitorTimer) {
+      clearInterval(this._monitorTimer);
+      this._monitorTimer = null;
+    }
+  }
+
+  /** Clear all owned caches. */
+  flush(): void {
+    this.pathNormCache.clear();
+    this.statCache.clear();
+    this.transformCache.clear();
+  }
+
+  /** Full cleanup — stop monitoring, flush caches. */
+  destroy(): void {
+    this._destroyed = true;
+    this.stopMonitoring();
+    this.flush();
+    this._pressureCallbacks.length = 0;
+  }
+
+  private _checkHeap(): void {
+    const perf = typeof performance !== 'undefined' ? (performance as any) : null;
+    if (!perf?.memory) return;
+    const usedMB = perf.memory.usedJSHeapSize / 1_048_576;
+    if (usedMB > this.options.heapWarnThresholdMB) {
+      for (const cb of this._pressureCallbacks) {
+        try { cb(); } catch { /* ignore */ }
+      }
+    }
+  }
+}

package/src/memory-volume.ts

@@ -3,6 +3,7 @@
 import type { VolumeSnapshot, VolumeEntry } from './engine-types';
 import { bytesToBase64, base64ToBytes } from './helpers/byte-encoding';
 import { MOCK_IDS, MOCK_FS } from './constants/config';
+import type { MemoryHandler } from './memory-handler';
 
 export interface VolumeNode {
   kind: 'file' | 'directory' | 'symlink';
@@ -172,8 +173,10 @@ export class MemoryVolume {
   private textDecoder = new TextDecoder();
   private activeWatchers = new Map<string, Set<ActiveWatcher>>();
   private subscribers = new Map<string, Set<VolumeEventHandler>>();
+  private _handler: MemoryHandler | null;
 
-  constructor() {
+  constructor(handler?: MemoryHandler | null) {
+    this._handler = handler ?? null;
     this.tree = {
       kind: 'directory',
       children: new Map(),
@@ -216,15 +219,55 @@ export class MemoryVolume {
     }
   }
 
+  // ---- Stats ----
+
+  getStats(): { fileCount: number; totalBytes: number; dirCount: number; watcherCount: number } {
+    let fileCount = 0;
+    let totalBytes = 0;
+    let dirCount = 0;
+    const walk = (node: VolumeNode) => {
+      if (node.kind === 'file') {
+        fileCount++;
+        totalBytes += node.content?.byteLength ?? 0;
+      } else if (node.kind === 'directory') {
+        dirCount++;
+        if (node.children) {
+          for (const child of node.children.values()) walk(child);
+        }
+      }
+    };
+    walk(this.tree);
+    let watcherCount = 0;
+    for (const set of this.activeWatchers.values()) watcherCount += set.size;
+    return { fileCount, totalBytes, dirCount, watcherCount };
+  }
+
+  /** Clean up all watchers, subscribers, and global listeners. */
+  dispose(): void {
+    this.activeWatchers.clear();
+    this.subscribers.clear();
+    this.globalChangeListeners.clear();
+    if (this._handler) {
+      this._handler.statCache.clear();
+      this._handler.pathNormCache.clear();
+    }
+  }
+
   // ---- Snapshot serialization ----
 
-  toSnapshot(excludePrefixes?: string[]): VolumeSnapshot {
+  toSnapshot(excludePrefixes?: string[], excludeDirNames?: Set<string>): VolumeSnapshot {
     const entries: VolumeEntry[] = [];
-    this.collectEntries('/', this.tree, entries, excludePrefixes);
+    this.collectEntries('/', this.tree, entries, excludePrefixes, excludeDirNames);
     return { entries };
   }
 
-  private collectEntries(currentPath: string, node: VolumeNode, result: VolumeEntry[], excludePrefixes?: string[]): void {
+  private collectEntries(
+    currentPath: string,
+    node: VolumeNode,
+    result: VolumeEntry[],
+    excludePrefixes?: string[],
+    excludeDirNames?: Set<string>,
+  ): void {
     if (excludePrefixes) {
       for (const prefix of excludePrefixes) {
         if (currentPath === prefix || currentPath.startsWith(prefix + '/')) return;
@@ -243,8 +286,10 @@ export class MemoryVolume {
       result.push({ path: currentPath, kind: 'directory' });
       if (node.children) {
         for (const [name, child] of node.children) {
+          // Skip excluded directory names at any depth (e.g. node_modules, .cache)
+          if (excludeDirNames && child.kind === 'directory' && excludeDirNames.has(name)) continue;
           const childPath = currentPath === '/' ? `/${name}` : `${currentPath}/${name}`;
-          this.collectEntries(childPath, child, result, excludePrefixes);
+          this.collectEntries(childPath, child, result, excludePrefixes, excludeDirNames);
         }
       }
     }
@@ -313,6 +358,10 @@ export class MemoryVolume {
   // ---- Path utilities ----
 
   private normalize(p: string): string {
+    if (this._handler) {
+      const cached = this._handler.pathNormCache.get(p);
+      if (cached !== undefined) return cached;
+    }
     if (!p.startsWith('/')) p = '/' + p;
     const parts = p.split('/').filter(Boolean);
     const resolved: string[] = [];
@@ -320,7 +369,9 @@ export class MemoryVolume {
       if (part === '..') resolved.pop();
       else if (part !== '.') resolved.push(part);
     }
-    return '/' + resolved.join('/');
+    const result = '/' + resolved.join('/');
+    if (this._handler) this._handler.pathNormCache.set(p, result);
+    return result;
   }
 
   // assumes pre-normalized input (starts with '/', no '..' or double slashes)
@@ -418,6 +469,8 @@ export class MemoryVolume {
       modified: Date.now(),
     });
 
+    if (this._handler) this._handler.invalidateStat(norm);
+
     if (notify) {
       this.triggerWatchers(norm, existed ? 'change' : 'rename');
       this.broadcast('change', norm, typeof data === 'string' ? data : this.textDecoder.decode(data));
@@ -433,13 +486,19 @@ export class MemoryVolume {
 
   statSync(p: string): FileStat {
     const norm = this.normalize(p);
+
+    if (this._handler) {
+      const cached = this._handler.statCache.get(norm);
+      if (cached !== undefined) return cached;
+    }
+
     const node = this.locate(norm);
     if (!node) throw makeSystemError('ENOENT', 'stat', p);
 
     const fileSize = node.kind === 'file' ? (node.content?.length || 0) : 0;
     const ts = node.modified;
 
-    return {
+    const result: FileStat = {
       isFile: () => node.kind === 'file',
       isDirectory: () => node.kind === 'directory',
       isSymbolicLink: () => false,
@@ -470,6 +529,9 @@ export class MemoryVolume {
       ctimeNs: BigInt(ts) * 1000000n,
       birthtimeNs: BigInt(ts) * 1000000n,
     };
+
+    if (this._handler) this._handler.statCache.set(norm, result);
+    return result;
   }
 
   lstatSync(p: string): FileStat {
@@ -579,6 +641,7 @@ export class MemoryVolume {
     if (target.kind !== 'file') throw makeSystemError('EISDIR', 'unlink', p);
 
     parent.children!.delete(name);
+    if (this._handler) this._handler.invalidateStat(norm);
     this.triggerWatchers(norm, 'rename');
     this.broadcast('delete', norm);
     this.notifyGlobalListeners(norm, 'unlink');
@@ -600,6 +663,7 @@ export class MemoryVolume {
     if (target.children!.size > 0) throw makeSystemError('ENOTEMPTY', 'rmdir', p);
 
     parent.children!.delete(name);
+    if (this._handler) this._handler.invalidateStat(norm);
   }
 
   renameSync(from: string, to: string): void {
@@ -938,7 +1002,7 @@ export class MemoryVolume {
     const self = this;
     const pending: Uint8Array[] = [];
     const handlers: Record<string, ((...args: unknown[]) => void)[]> = {};
-    const enc = new TextEncoder();
+    const enc = this.textEncoder;
 
     return {
       write(data: string | Uint8Array): boolean {

package/src/packages/installer.ts

@@ -13,6 +13,9 @@ import { downloadAndExtract } from "./archive-extractor";
 import { convertPackage, prepareTransformer } from "../module-transformer";
 import type { PackageManifest } from "../types/manifest";
 import * as path from "../polyfills/path";
+import type { IDBSnapshotCache } from "../persistence/idb-cache";
+import { quickDigest } from "../helpers/digest";
+import { base64ToBytes } from "../helpers/byte-encoding";
 
 // ---------------------------------------------------------------------------
 // Public types
@@ -87,11 +90,13 @@ export class DependencyInstaller {
   private vol: MemoryVolume;
   private registryClient: RegistryClient;
   private workingDir: string;
+  private _snapshotCache: IDBSnapshotCache | null;
 
-  constructor(vol: MemoryVolume, opts: { cwd?: string } & RegistryConfig = {}) {
+  constructor(vol: MemoryVolume, opts: { cwd?: string; snapshotCache?: IDBSnapshotCache | null } & RegistryConfig = {}) {
     this.vol = vol;
     this.registryClient = new RegistryClient(opts);
     this.workingDir = opts.cwd || "/";
+    this._snapshotCache = opts.snapshotCache ?? null;
   }
 
   // -----------------------------------------------------------------------
@@ -157,6 +162,37 @@ export class DependencyInstaller {
     const raw = this.vol.readFileSync(jsonPath, "utf8");
     const manifest: PackageManifest = JSON.parse(raw);
 
+    // Check IDB snapshot cache — skip full install if we have a cached node_modules
+    const cacheKey = this._snapshotCache ? quickDigest(raw) : null;
+    if (this._snapshotCache && cacheKey) {
+      try {
+        const cached = await this._snapshotCache.get(cacheKey);
+        if (cached) {
+          onProgress?.("Restoring cached node_modules...");
+          const { entries } = cached;
+          // Restore only node_modules entries from the snapshot
+          for (const entry of entries) {
+            if (!entry.path.includes('/node_modules/')) continue;
+            if (entry.kind === 'directory') {
+              if (!this.vol.existsSync(entry.path)) {
+                this.vol.mkdirSync(entry.path, { recursive: true });
+              }
+            } else if (entry.kind === 'file' && entry.data) {
+              const parentDir = entry.path.substring(0, entry.path.lastIndexOf('/')) || '/';
+              if (parentDir !== '/' && !this.vol.existsSync(parentDir)) {
+                this.vol.mkdirSync(parentDir, { recursive: true });
+              }
+              this.vol.writeFileSync(entry.path, base64ToBytes(entry.data));
+            }
+          }
+          onProgress?.(`Restored ${entries.length} cached entries`);
+          return { resolved: new Map(), newPackages: [] };
+        }
+      } catch {
+        // Cache miss or error — proceed with normal install
+      }
+    }
+
     onProgress?.("Resolving dependency tree...");
 
     const resolutionOpts: ResolutionConfig = {
@@ -170,6 +206,18 @@ export class DependencyInstaller {
 
     const newPkgs = await this.materializePackages(tree, flags);
 
+    // Cache the installed node_modules snapshot for future reuse
+    if (this._snapshotCache && cacheKey && newPkgs.length > 0) {
+      try {
+        const snapshot = this.vol.toSnapshot();
+        // Filter to only node_modules entries to keep cache lean
+        const nmSnapshot = {
+          entries: snapshot.entries.filter(e => e.path.includes('/node_modules/')),
+        };
+        await this._snapshotCache.set(cacheKey, nmSnapshot);
+      } catch { /* cache write failure is non-fatal */ }
+    }
+
     onProgress?.(`Installed ${tree.size} package(s)`);
 
     return { resolved: tree, newPackages: newPkgs };