@n3bula/sandbox 0.0.1-alpha.1

package/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+Copyright ©️ 2026 Moriart47<wang_jn_xian@163.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,51 @@
+# `@n3bula/sandbox`
+
+### Simple Sandbox for Node.js module quick test
+Just use for debug
+Debug the current process without restart process
+
+## Install
+
+```sh
+npm install @n3bula/sandbox
+# or
+yarn add @n3bula/sandbox
+# or
+pnpm add @n3bula/sandbox
+```
+
+## Example
+
+```ts
+// server.ts
+import net from 'net';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { createSandbox } from '@n3bula/sandbox';
+const PORT = 4000;
+const server = net.createServer();
+server.listen(PORT, () => console.log(`TCP server listening on ${PORT}`));
+server.on('error', err => console.error('server error', err));
+const destroy = () => {
+  server.close();
+  process.exit();
+};
+process.on('SIGINT', destroy);
+process.on('SIGTERM', destroy);
+
+createSandbox('sandbox', resolve(fileURLToPath(dirname(import.meta.url)), './client.ts'), { server });
+```
+
+```ts
+// client.ts
+console.log(1); // change to console.log(server);
+// will print current server instance without restart server
+```
+
+## Author
+
+- [Moriarty47](https://github.com/Moriarty47)
+
+## License
+
+[The MIT License(MIT)](https://github.com/Moriarty47/n3bula/blob/main/LICENSE)

package/dist/index.d.mts

@@ -0,0 +1,4 @@
+//#region src/sandbox.d.ts
+declare function createSandbox(name: string, watchFilePath: string, globals?: {}): void;
+//#endregion
+export { createSandbox };

package/dist/index.mjs

@@ -0,0 +1,128 @@
+import vm from "node:vm";
+import EventEmitter from "node:events";
+import { readFile, stat, watch } from "node:fs";
+import { echo } from "@n3bula/echo/node";
+//#region src/logger.ts
+const createLogger = (tag) => {
+	const logger = ((...msg) => {
+		tag ? echo.fg.cyan(tag, ...msg) : echo.fg.cyan(...msg);
+	});
+	logger.info = (...msg) => {
+		tag ? echo.fg("#66b5ff")(tag, ...msg) : echo.fg("#66b5ff")(...msg);
+	};
+	logger.warn = (...msg) => {
+		tag ? echo.fg("#ff9966")(tag, ...msg) : echo.fg("#ff9966")(...msg);
+	};
+	logger.error = (...msg) => {
+		tag ? echo.fg.orangeRed(tag, ...msg) : echo.fg.orangeRed(...msg);
+	};
+	return logger;
+};
+const logger = createLogger("@n3bula/sandbox");
+//#endregion
+//#region src/file-watcher.ts
+const DEBOUNCE_MS = 200;
+const READ_RETRY_MS = 100;
+const MAX_READ_RETRIES = 5;
+var FileWatcher = class extends EventEmitter {
+	timer = null;
+	lastStat = null;
+	readRetries = 0;
+	watcher;
+	constructor(filePath) {
+		super();
+		this.filePath = filePath;
+		this.scheduleRead = this.scheduleRead.bind(this);
+		this.startWatch();
+	}
+	safeReadAndNotify() {
+		readFile(this.filePath, "utf8", (err, data) => {
+			if (err) {
+				if (err.code === "ENOENT" && this.readRetries < MAX_READ_RETRIES) {
+					this.readRetries++;
+					setTimeout(this.safeReadAndNotify, READ_RETRY_MS);
+					return;
+				}
+				logger.error("Read error:", err.code, err.message);
+				return;
+			}
+			this.readRetries = 0;
+			stat(this.filePath, (err2, fileStat) => {
+				if (!err2) {
+					if (this.lastStat && fileStat.mtimeMs === this.lastStat.mtimeMs && fileStat.size === this.lastStat.size) return;
+					this.lastStat = fileStat;
+				}
+				this.emit("change", data.split(/\r?\n/).filter((l) => !/^\s*\/\//.test(l)).map((l) => l.trim()).join(" "));
+			});
+		});
+	}
+	scheduleRead() {
+		if (this.timer) clearTimeout(this.timer);
+		this.timer = setTimeout(() => {
+			this.timer = null;
+			this.safeReadAndNotify();
+		}, DEBOUNCE_MS);
+	}
+	startWatch() {
+		try {
+			const watcher = watch(this.filePath, {
+				encoding: "utf8",
+				persistent: true
+			}, this.scheduleRead);
+			watcher.on("error", (err) => {
+				logger.error("fs.watch error", err);
+				if (watcher) try {
+					watcher.close();
+				} catch {}
+			});
+			stat(this.filePath, (err, fileStat) => {
+				if (!err) this.lastStat = fileStat;
+			});
+			logger("Watching", this.filePath);
+			this.watcher = watcher;
+		} catch (error) {
+			logger.error("fs.watch error", error.message);
+		}
+	}
+	destroy() {
+		if (this.watcher && typeof this.watcher.close === "function") try {
+			this.watcher.close();
+		} catch {}
+	}
+};
+//#endregion
+//#region src/sandbox.ts
+function createContext(sandboxGlobals = {}) {
+	return vm.createContext({
+		console,
+		setTimeout,
+		setInterval,
+		clearTimeout,
+		clearInterval,
+		fetch: typeof fetch !== "undefined" ? fetch : void 0,
+		...sandboxGlobals
+	});
+}
+function createSandbox(name, watchFilePath, globals = {}) {
+	const sandboxContext = createContext({
+		...globals,
+		__sandbox_name: name
+	});
+	function runCode(code) {
+		return new vm.Script(`(async () => { ${code} })()`).runInContext(sandboxContext, { timeout: 2e3 }).then((res) => res).catch((err) => {
+			logger.error(err.name, err.message);
+		});
+	}
+	const watcher = new FileWatcher(watchFilePath);
+	watcher.on("change", (code) => {
+		runCode(code);
+	});
+	const destroy = () => {
+		watcher.destroy();
+		process.exit();
+	};
+	process.on("SIGINT", destroy);
+	process.on("SIGTERM", destroy);
+}
+//#endregion
+export { createSandbox };

package/example/client.ts

@@ -0,0 +1 @@
+console.log(server);

package/example/server.ts

@@ -0,0 +1,20 @@
+import net from 'net';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+import { createSandbox } from '../src';
+
+const PORT = 4000;
+const server = net.createServer();
+server.listen(PORT, () => console.log(`TCP server listening on ${PORT}`));
+const destroy = () => {
+  server.close();
+  process.exit();
+};
+process.on('SIGINT', destroy);
+process.on('SIGTERM', destroy);
+
+const file = resolve(fileURLToPath(dirname(import.meta.url)), './client.ts');
+createSandbox('sandbox', file, {
+  server,
+});

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@n3bula/sandbox",
+  "version": "0.0.1-alpha.1",
+  "description": "Simple Sandbox for Node.js module quick test",
+  "type": "module",
+  "main": "dist/index.mjs",
+  "typings": "dist/index.d.mts",
+  "keywords": [
+    "sandbox",
+    "node"
+  ],
+  "contributors": [
+    {
+      "name": "Moriarty47",
+      "email": "wang_jn_xian@163.com"
+    }
+  ],
+  "homepage": "https://github.com/Moriarty47/n3bula/tree/main/packages/sandbox#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Moriarty47/n3bula.git",
+    "directory": "packages/sandbox"
+  },
+  "author": {
+    "name": "Moriarty47",
+    "email": "wang_jn_xian@163.com"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "tsdown": "^0.21.5"
+  },
+  "dependencies": {
+    "@n3bula/echo": "^0.1.0-alpha.4"
+  },
+  "scripts": {
+    "dev": "tsx --experimental-vm-modules example/server.ts",
+    "build": "tsdown"
+  }
+}

package/src/file-watcher.ts

@@ -0,0 +1,90 @@
+import EventEmitter from 'node:events';
+import { FSWatcher, readFile, stat, Stats, watch } from 'node:fs';
+
+import { logger } from './logger';
+
+const DEBOUNCE_MS = 200;
+const READ_RETRY_MS = 100;
+const MAX_READ_RETRIES = 5;
+
+export class FileWatcher extends EventEmitter {
+  timer: NodeJS.Timeout | null = null;
+  lastStat: Stats | null = null;
+  readRetries = 0;
+  watcher!: FSWatcher;
+  constructor(public filePath: string) {
+    super();
+    this.scheduleRead = this.scheduleRead.bind(this);
+    this.startWatch();
+  }
+
+  safeReadAndNotify() {
+    readFile(this.filePath, 'utf8', (err, data) => {
+      if (err) {
+        if (err.code === 'ENOENT' && this.readRetries < MAX_READ_RETRIES) {
+          this.readRetries++;
+          setTimeout(this.safeReadAndNotify, READ_RETRY_MS);
+          return;
+        }
+        logger.error('Read error:', err.code, err.message);
+        return;
+      }
+      this.readRetries = 0;
+      stat(this.filePath, (err2, fileStat) => {
+        if (!err2) {
+          if (this.lastStat && fileStat.mtimeMs === this.lastStat.mtimeMs && fileStat.size === this.lastStat.size)
+            return;
+          this.lastStat = fileStat;
+        }
+        this.emit(
+          'change',
+          data
+            .split(/\r?\n/)
+            .filter(l => !/^\s*\/\//.test(l))
+            .map(l => l.trim())
+            .join(' '),
+        );
+      });
+    });
+  }
+
+  scheduleRead() {
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      this.safeReadAndNotify();
+    }, DEBOUNCE_MS);
+  }
+
+  startWatch() {
+    try {
+      const watcher = watch(this.filePath, { encoding: 'utf8', persistent: true }, this.scheduleRead);
+
+      watcher.on('error', err => {
+        logger.error('fs.watch error', err);
+        if (watcher) {
+          try {
+            watcher.close();
+          } catch {}
+        }
+      });
+
+      stat(this.filePath, (err, fileStat) => {
+        if (!err) this.lastStat = fileStat;
+      });
+
+      logger('Watching', this.filePath);
+      this.watcher = watcher;
+    } catch (error: any) {
+      logger.error('fs.watch error', error.message);
+    }
+  }
+
+  destroy() {
+    if (this.watcher && typeof this.watcher.close === 'function') {
+      try {
+        this.watcher.close();
+      } catch {}
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { createSandbox } from './sandbox';

package/src/logger.ts

@@ -0,0 +1,28 @@
+import { echo } from '@n3bula/echo/node';
+
+export const createLogger = (tag?: string) => {
+  const logger = ((...msg: any[]) => {
+    tag ? echo.fg.cyan(tag, ...msg) : echo.fg.cyan(...msg);
+  }) as {
+    (...msg: any[]): void;
+    info(...msg: any[]): void;
+    warn(...msg: any[]): void;
+    error(...msg: any[]): void;
+  };
+
+  logger.info = (...msg: any[]) => {
+    tag ? echo.fg('#66b5ff')(tag, ...msg) : echo.fg('#66b5ff')(...msg);
+  };
+
+  logger.warn = (...msg: any[]) => {
+    tag ? echo.fg('#ff9966')(tag, ...msg) : echo.fg('#ff9966')(...msg);
+  };
+
+  logger.error = (...msg: any[]) => {
+    tag ? echo.fg.orangeRed(tag, ...msg) : echo.fg.orangeRed(...msg);
+  };
+
+  return logger;
+};
+
+export const logger = createLogger('@n3bula/sandbox');

package/src/sandbox.ts

@@ -0,0 +1,46 @@
+import vm from 'node:vm';
+
+import { FileWatcher } from './file-watcher';
+import { logger } from './logger';
+
+function createContext(sandboxGlobals = {}) {
+  const context = vm.createContext({
+    console,
+    setTimeout,
+    setInterval,
+    clearTimeout,
+    clearInterval,
+    fetch: typeof fetch !== 'undefined' ? fetch : undefined,
+    ...sandboxGlobals,
+  });
+  return context;
+}
+
+export function createSandbox(name: string, watchFilePath: string, globals = {}) {
+  const sandboxContext = createContext({
+    ...globals,
+    __sandbox_name: name,
+  });
+
+  function runCode(code: string) {
+    const script = new vm.Script(`(async () => { ${code} })()`);
+    const result: Promise<any> = script.runInContext(sandboxContext, { timeout: 2000 });
+    return result
+      .then(res => res)
+      .catch(err => {
+        logger.error(err.name, err.message);
+      });
+  }
+
+  const watcher = new FileWatcher(watchFilePath);
+  watcher.on('change', code => {
+    runCode(code);
+  });
+
+  const destroy = () => {
+    watcher.destroy();
+    process.exit();
+  };
+  process.on('SIGINT', destroy);
+  process.on('SIGTERM', destroy);
+}

package/src/wasted-module.ts

@@ -0,0 +1,172 @@
+import vm from 'node:vm';
+import Module from 'node:module';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { PROTOCOL_FILE, PROTOCOL_NODE, resolvedProtocols } from './utils';
+
+function createContext(sandboxGlobals = {}) {
+  const context = vm.createContext({
+    console,
+    setTimeout,
+    setInterval,
+    clearTimeout,
+    clearInterval,
+    fetch: typeof fetch !== 'undefined' ? fetch : undefined,
+    ...sandboxGlobals,
+  });
+  return context;
+}
+
+export function createSandbox(name: string, globals = {}) {
+  const memoryModules = new Map<string, { code: string; mtime: number }>();
+
+  const moduleInstances = new Map<string, vm.Module>();
+
+  const sandboxContext = createContext({
+    ...globals,
+    __sandbox_name: name,
+    __node_import_fallback: (id: string) => {
+      try {
+        return Module.createRequire(import.meta.url)(id);
+      } catch (error) {
+        // try without node: prefix
+        return Module.createRequire(import.meta.url)(id);
+      }
+    },
+  });
+
+  async function resolveSpecifier(specifier: string, referrer?: string) {
+    const isFileProtocol = !!(referrer && referrer.startsWith(PROTOCOL_FILE));
+    try {
+      const url = new URL(specifier, isFileProtocol ? referrer : undefined);
+      if (resolvedProtocols.includes(url.protocol)) {
+        return url.toString();
+      }
+    } catch (error) {
+      // not a URL, other resolve solution
+    }
+
+    if (memoryModules.has(specifier)) return specifier;
+
+    try {
+      const require = Module.createRequire(isFileProtocol ? referrer : pathToFileURL(`${process.cwd()}/`).toString());
+      const resolved = require.resolve(specifier);
+      return pathToFileURL(resolved).toString();
+    } catch (error) {
+      // fallback: try resolving as relative to referrer filesystem path
+      if (isFileProtocol) {
+        const refPath = fileURLToPath(referrer);
+        const candidate = resolve(dirname(refPath), specifier);
+        if (existsSync(candidate)) {
+          const final = pathToFileURL(candidate).toString();
+          return final;
+        }
+      }
+      // last resort: return specifier as-is, link may fail
+      return specifier;
+    }
+  }
+
+  async function loadSource(resolved: string) {
+    const memoryModule = memoryModules.get(resolved);
+    if (memoryModule) return { source: memoryModule.code, url: resolved };
+
+    if (resolved.startsWith(PROTOCOL_FILE)) {
+      const filePath = fileURLToPath(resolved);
+      const code = await readFile(filePath, 'utf8');
+      return { source: code, url: resolved };
+    }
+
+    if (resolved.startsWith(PROTOCOL_NODE)) {
+      const pkg = resolved.slice(PROTOCOL_NODE.length);
+      const code = `export default globalThis.__node_import_fallback('${pkg}');\nexport const __esModule = true;`;
+      return { source: code, url: resolved };
+    }
+
+    try {
+      const code = await readFile(resolved, 'utf8');
+      return { source: code, url: resolved };
+    } catch {
+      // fallback: create a wrapper that imports via dynamic import
+      const code = `export default await import(${JSON.stringify(resolved)});\n`;
+      return { source: code, url: resolved };
+    }
+  }
+
+  async function linker(specifier: string, referencingModule: vm.Module) {
+    const refUrl = (('identifier' in referencingModule && referencingModule.identifier) as string) || undefined;
+    const resolved = await resolveSpecifier(specifier, refUrl);
+    const { source, url } = await loadSource(resolved);
+
+    const moduleInstance = moduleInstances.get(url);
+    if (moduleInstance) return moduleInstance;
+
+    const module = new vm.SourceTextModule(source, {
+      context: sandboxContext,
+      identifier: url,
+      initializeImportMeta: (meta, module) => (meta.url = module.identifier),
+    });
+
+    moduleInstances.set(url, module);
+
+    // link dependencies recursively inside vm's linker; vm.Module.link willcall our linker for each import
+    await module.link(linker);
+    return module;
+  }
+
+  function registerModule(specifier: string, code: string) {
+    memoryModules.set(specifier, { code, mtime: Date.now() });
+    // invalidate instance cache
+    moduleInstances.delete(specifier);
+  }
+
+  function unnregisterModule(specifier: string) {
+    memoryModules.delete(specifier);
+    moduleInstances.delete(specifier);
+  }
+
+  async function runModule(
+    code: string,
+    specifier: string = `mem://${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    globals = {},
+  ) {
+    Object.assign(sandboxContext, globals);
+    registerModule(specifier, code);
+
+    const resolved = await resolveSpecifier(specifier);
+    const { source, url } = await loadSource(resolved);
+
+    const module = new vm.SourceTextModule(source, {
+      context: sandboxContext,
+      identifier: url,
+      initializeImportMeta: (meta, m) => (meta.url = m.identifier),
+    });
+
+    moduleInstances.set(url, module);
+
+    await module.link(linker);
+
+    const result = await module.evaluate();
+    return {
+      module,
+      namespace: module.namespace,
+      status: module.status,
+      evaluationResult: result,
+    };
+  }
+
+  function hotReload(specifier: string, newCode: string) {
+    unnregisterModule(specifier);
+    registerModule(specifier, newCode);
+    return runModule(newCode, specifier);
+  }
+
+  return {
+    registerModule,
+    unnregisterModule,
+    runModule,
+    hotReload,
+  };
+}

package/src/wasted-socket.ts

@@ -0,0 +1,90 @@
+import net, { Socket } from 'node:net';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { IS_WIN } from './utils';
+import { chmodSync, existsSync, unlinkSync } from 'node:fs';
+import { logger } from './logger';
+
+function getSocketPath(name: string = 'n3bula-sandbox') {
+  if (IS_WIN) {
+    const pipeName = name.replace(/[\\/:\*\?"<>\|]/g, '_');
+    return `\\\\.\\pipe\\${pipeName}`;
+  }
+  return join(tmpdir(), `${name}.sock`);
+}
+
+function cleanupSocketFile(socketPath: string) {
+  if (IS_WIN) return;
+  try {
+    if (existsSync(socketPath)) unlinkSync(socketPath);
+  } catch {}
+}
+
+export async function createSocketServer(name: string, connectionListener: (socket: Socket) => void) {
+  const socketPath = getSocketPath(name);
+  cleanupSocketFile(socketPath);
+
+  const server = net.createServer(socket => {
+    socket.on('end', () => socket.end());
+    socket.on('close', () => logger('server closed'));
+    socket.on('error', err => logger.error('server', err));
+    connectionListener(socket);
+  });
+
+  server.listen(socketPath, () => {
+    logger('Listening on', socketPath);
+    if (IS_WIN) return;
+    try {
+      chmodSync(socketPath, 0o600);
+    } catch {}
+  });
+
+  const cleanup = () => {
+    server.close();
+    cleanupSocketFile(socketPath);
+  };
+  const destroy = () => {
+    cleanup();
+    process.exit();
+  };
+  process.on('exit', cleanup);
+  process.on('SIGINT', destroy);
+  process.on('SIGTERM', destroy);
+
+  return { server, path: socketPath };
+}
+
+function connectSocket(name: string, onConnect?: (socket: Socket) => void) {
+  const socketPath = getSocketPath(name);
+  return new Promise<string>((resolve, reject) => {
+    const client = net.createConnection(socketPath, () => onConnect?.(client));
+    client.setEncoding('utf8');
+
+    client.on('close', () => logger('client closed'));
+    client.on('error', err => logger.error('client', err));
+
+    let resp = '';
+    client.on('data', d => (resp += d));
+
+    client.on('end', () => {
+      try {
+        resolve(JSON.parse(resp));
+      } catch (e) {
+        reject(e);
+      }
+      client.end();
+    });
+  });
+}
+
+export function clientSend(name: string, code: string) {
+  return connectSocket(name, socket => {
+    socket.write(
+      `${code
+        .split(/\r?\n/)
+        .filter(l => !/^\s*\/\//.test(l))
+        .map(l => l.trim())
+        .join(' ')}\n`,
+    );
+  });
+}

package/src/wasted-utils.ts

@@ -0,0 +1,4 @@
+export const PROTOCOL_FILE = 'file:';
+export const PROTOCOL_NODE = 'node:';
+export const resolvedProtocols = [PROTOCOL_NODE, PROTOCOL_FILE, 'data:', 'http:', 'https:'];
+export const IS_WIN = process.platform === 'win32';

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "rootDir": ".",
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "es2022",
+    "types": ["node"],
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "noEmit": true,
+    "esModuleInterop": true,
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": false,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["tsdown.config.ts", "src", "example"]
+}

package/tsdown.config.ts

@@ -0,0 +1,5 @@
+import { defineConfig } from 'tsdown';
+
+export default defineConfig({
+  entry: ['./src/index.ts'],
+});